Using Swagger UI to explore REST API requests

This article explains how to use Swagger UI to explore the Autotask REST API.

Overview

Swagger UI (external link) is a web-based application that empowers you to inspect the Autotask REST API visually. With Swagger, you can view all of the available REST entities and their functions, construct test requests, and view query results.

Use Swagger if:

  • You'd like to browse the structure of the API from an all-in-one view.
  • You'd like a comprehensive index of call examples for all API entities.
  • You'd like to be able to generate sample API output from a point-and-click interface.

Proceed to the next section of this article to learn how to get started with the application. For Swagger application support, visit the SwaggerHub Support page external link).

Connecting to your Swagger UI instance

To connect to Swagger UI, in a web browser, navigate to [your platform here]/swagger/ui/index.

Replace [your platform here] with the platform-specific URL for your region from the list below.

IMPORTANT  You must use the platform-specific URL associated with your user account. Swagger is unable to authenticate user sessions originating from non-native zones.

Zone API URL
Pre-release https://webservices2.autotask.net/atservicesrest/swagger/ui/index
Pre-release (UK) https://webservices11.autotask.net/atservicesrest/swagger/ui/index
Limited Release https://webservices1.autotask.net/atservicesrest/swagger/ui/index
Limited Release (UK) https://webservices17.autotask.net/atservicesrest/swagger/ui/index
America East https://webservices3.autotask.net/atservicesrest/swagger/ui/index
America East 2 https://webservices14.autotask.net/atservicesrest/swagger/ui/index
America West https://webservices5.autotask.net/atservicesrest/swagger/ui/index
America West 2 https://webservices15.autotask.net/atservicesrest/swagger/ui/index
UK https://webservices4.autotask.net/atservicesrest/swagger/ui/index
UK2 https://webservices16.autotask.net/atservicesrest/swagger/ui/index
Australia / New Zealand https://webservices6.autotask.net/atservicesrest/swagger/ui/index
Pre-Release (Deutsch) https://prde.autotask.net/atservicesrest/swagger/ui/index
Pre-Release (Español) https://pres.autotask.net/atservicesrest/swagger/ui/index
German (Deutsch) https://webservices18.autotask.net/atservicesrest/swagger/ui/index
EU1 (English Europe and Asia) https://webservices19.autotask.net/atservicesrest/swagger/ui/index
Spanish (Español) https://webservices12.autotask.net/atservicesrest/swagger/ui/index

Navigating the interface

Swagger UI lists all available API entities that relate to different areas of the product. You can expand or collapse the entity list to expose varying levels of detail. When expanded, each entity shows the syntax of its available operations, along with the request method (e.g., GET, POST, PUT PATCH, or DELETE) and sample values.

When collapsed, the list shows entity names only. You can click each entity's name to expand it and view a higher level of detail.


The ActionTypes entity shown in Swagger UI with its fields expanded.

To view granular information about a specific request, click its name in the expanded entity view.

The expanded request detail may include the following sections:

Section Description
queryModel The Model option displays the syntax structure that requests of this type to the API should follow. The Edit Value option enables you to enter an XML-formatted query that follows the designated format.
ApiIntegrationCode When making requests to the API, enter your integration code in this field.
UserName To authenticate to the API for your instance, enter the name of an API user account here.
Secret Enter the password for your API user in this field.

ImpersonationResourceId

Supply a value for this header when you use the REST API to impersonate another resource. If the entity supports impersonation (for example, TicketNote), then any action calls made with a valid ImpersonationResourceId will appear as if they were created by the resource associated with that ID instead of the resource associated with the UserName header. Both the entity and action must be supported; otherwise, the API will ignore the ImpersonationResourceId.

Responses

This field contains sample and actual responses that you may receive when calling the entity with the selected query.

Making a test request

To make a test request to the API via Swagger, perform the following steps.

1. Select an entity and a query type.

2. In the expanded request detail window, click Try it out.

Screenshot of a POST request for ContactGroupContacts in the Swagger UI with a red box drawn around the 'Try it out' option.

3. Fill out any required fields that populate and provide a query in the queryModel box.

A screenshot of a user completing required fields in the Swagger UI for the REST API.

4. When you're ready to run the query, click Execute.

The Execute button in the Swagger UI with a red box highlighting it.

5. Responses to your query will appear in the Responses section of the page for the selected entity.

Screenshot of the curl and request URL syntax, as well as the query response, in the Swagger UI. The Download button is visible.

6. Fields with a Download button next to them indicate that a JSON file containing the response output is available for you to save to your local device.

IMPORTANT  When making requests, it is important to use the following base URL before appending the request: [API URL]/atservicesrest/v1.0/

EXAMPLE  For example, if the required request was /v1.0/ActionTypes, the correct format would be [API URL]/atservicesrest/v1.0/ActionTypes.

Additional resources