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
- 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.
- 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.
- 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:
- Open the application's API reference and pick the service.
- 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.
- 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.
- Open the API reference and choose an endpoint.
- Choose Test Request.
- 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
| To | You need |
|---|---|
| Read a service's API reference | Applications: Read |
| Set or clear a service's API description file | Applications: Update |
| Send Try it requests to a live preview | Applications: Read and Sessions: Read |
| Send Try it requests to a deployed environment | Applications: Update |
Limits
| Limit | Value |
|---|---|
| API description file | 4 MB, in one file: references to other files are not followed |
| Try it request body | 1 MB |
| Try it answer | Up to 4 MB; a longer answer is cut, and says so |
| Try it time | 30 seconds |
| Try it requests | 60 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.