Engineering

API reference

When a web service of an application has an OpenAPI (or Swagger) file in its repository, Productmind shows it as a browsable API reference: its endpoints grouped by tag, with their parameters, request and response schemas, examples and code samples. Try it sends real requests to a live preview of the application or to one of its deployed environments, and shows the answers.

Working with an API reference

To browse a service's API reference

  1. Open the application and choose API reference, under Run in its list of sections. You can also choose View API reference on a web service's line in Services.
  2. The reference opens on the first service that has an API description. The list of applications folds away to give it room; choose the list button at the top left to bring it back.
  3. To switch to another service, or to an API description no service uses, choose the service's name at the top of the reference and pick another.

The bar at the top says which file the reference is read from, on which branch, and whether it was found automatically or set on the service. Choose the file's name to open it at your git provider. It also shows the OpenAPI version, the number of operations, and where Try it can send. Use Search, above the list of endpoints, to find one.

The file is read from the application's Base branch. Productmind finds it automatically: a file named openapi.json, openapi.yaml, swagger.json or swagger.yaml (or .yml), or ending in .openapi.json or .openapi.yaml, outside dependency, build and test folders. With one web service, it takes the file nearest the repository's root. With several, each takes the file in a folder named like the service.

To set a service's API description file

If the file has another name, is somewhere else, or belongs to another service:

  1. Open the application's API reference and pick the service.
  2. Choose Change file, or Set the file's path when none was found. In Services, the service's line has the same choice: Change, or Set path.
  3. Search the repository's files and pick the file, or type its path and press Enter.

To go back to finding the file automatically, choose Change file, then Find it automatically.

To try a request

Try it in the API reference sends a real request and shows the answer. It sends only to:

  • a live preview of a session that runs this application, while the preview is running. Its API must answer under the preview's address, as a live preview serves it.
  • one of the application's deployed environments. Its address is the environment's live address; you can change the host to any host under the environment's domain, such as api.example.com.

The bar at the top of the reference says where requests go: Try it with the first live preview or environment it can reach (point at it to see them all), or Try it off, with what to do to turn it on.

  1. Open the API reference and choose an endpoint.
  2. Choose Test Request.
  3. Pick the live preview or the environment in the server list, fill in the parameters and the body, and choose Send.

Each endpoint shows a code sample for the selected server; choose another language above it, such as Python or JavaScript.

Productmind sends the request for you: your browser never calls the address itself. The servers listed in the file are shown, but a request to one of them is not sent, and the answer says where Try it can send. When there is no running preview and no deployed environment, Test Request is hidden.

On a Production environment, any request other than GET, HEAD or OPTIONS asks Send this request to Production? first. Every request sent to an environment is recorded in the audit log: its method, path, status and environment, never its headers or body.

Permissions

ToYou need
Read a service's API referenceApplications: Read
Set or clear a service's API description fileApplications: Update
Send Try it requests to a live previewApplications: Read and Sessions: Read
Send Try it requests to a deployed environmentApplications: Update

See Roles and permissions.

Limits

LimitValue
API description file4 MB, in one file: references to other files are not followed
Try it request body1 MB
Try it answerUp to 4 MB; a longer answer is cut, and says so
Try it time30 seconds
Try it requests60 a minute

Troubleshooting

A live preview answers 404

Try it reaches a preview at the preview's own address, under the session and the port. An API that only answers at the root of its server answers 404 there: make it answer under the address the live preview gives it.

The reference shows an older version of the API

The file is read from the application's Base branch, so a change a session made to it shows once it is merged there.

Last modified on