How to Use Swagger Documentation [Information]

Modified on Wed, 22 Jan at 5:38 PM

Swagger provides a detailed reference for working with Techdinamics' Application Programming Interfaces (APIs), helping you interact seamlessly with our products through well-documented methods, parameters, and responses.

GETTING STARTED

Refer to the following resources to start using Techdinamics' APIs for your chosen product:

Each product has its own Swagger URL available in the resources listed above.

SWAGGER SECTIONS

The Swagger documentation is divided into the following sections:

A) API Authorization: This section allows you to enter your API credentials to test methods within Swagger. For details on how to obtain your API credentials, please refer to the previously listed resources.

WARNING: API credentials are sensitive and should be handled securely. Avoid sharing or exposing them.

B) Methods: This section describes the available methods, organized by categories.

C) Models: This section details the available objects.

Each method in the Swagger documentation includes the following information:

D) API Method Summary:

HTTP method: HTTP method to be used.
Endpoint URL: Endpoint URL to be used.

NOTE: When calling an API method, combine the portal's base URL with the API method's endpoint. E.g.: If your portal is https://myportal.techdinamics.io and the API method's endpoint is /api/v2/category-x/method-y, the URL to be used for calling that API method will be https://mycompany.techdinamics.io/api/v2/category-x/method-y
Description: Detailed description of what that API method does.
Lock icon: Indicates if that method is available for testing within Swagger:
- If the lock is open, you need to log in in Swagger to access this functionality. Refer to section A to know how to do this.
- If the lock is closed, you are already signed in and are able to try this API method within Swagger.

E) Request Parameters: This section details the API method signature, including the parameters that can be passed to the method.

F) Responses: This section describes the possible results that can be returned by the method, organized by HTTP response codes.

Request and response data is presented in two views:

If the data is an object, you can choose the between the following view
- Example value: This view displays an example of the data structure to use.
- Model: This view displays the object definition, which is the expected abstract data structure.
If data is a native data type, it shows values and description:

G) Try it out: Enables the quick test mode, opening the fields to be completed and an Execute button to run the API method with the parameters you provided.

NOTE: This option requires prior authorization to be enabled. The "Try it out" functionality may be limited to a certain number of tests or a specific set of methods, according to Techdinamics' policies.

You will get the result in the response section: