Using the Swagger UI

Nearly all communication to the Tator backend is accomplished via an OpenAPI 3.0 compliant REST API. This allows for better maintainability of client libraries such as tator-py and tator-r through OpenAPI Generator, and also makes it easy to view REST documentation and build and execute requests using Swagger UI.

This tutorial will explain how to access the REST interface, browse its documentation, and execute queries. To begin, you must have installed Tator and created a project.

Go to the REST interface

The REST interface can be accessed by clicking the REST Interface link in the main nav.

This will open the Swagger UI.

Make a query

Each row in the REST interface corresponds to an endpoint and method. For example, to retrieve a list of media from a project, go to the GET method for the Medias endpoint and click to expand. This will display documentation for the endpoint, including a description, query parameters, and responses. To use the endpoint, click the Try it out button.

Fill in a project ID for the project field. You can optionally fill in other query parameters to narrow down your query. When you are done modifying parameters, scroll down and click the Execute button.

After a moment the response will be displayed, as well as the curl command used to send the request, request URL, and response headers.

View schemas for request bodies and responses

Often you simply need to view the format of a request body to make a POST or PATCH request, or to see the format of a response that is retrieving data. In both cases, you can access these by clicking on the Schema button next to the Example Value. This will display full documentation for the given model. Alternatively, you can browse all models directly by scrolling to the end of the REST interface page.