Using the REST API
This topic introduces the REST API and Swagger UI.
Introduction to the REST API
The REST API is intended to be used by a client script or program to interact with and control a TrueSight Network Automation application server from a remote machine. You can use the API to perform create, retrieve, update, and delete operations on the following components:
- All types of network spans (realms, combo groups, groups, and devices)
- Jobs and predefined jobs
- Rule sets and rules
You can also use the API to retrieve other components, such as device agents, templates, and OS images, that are referenced by network spans, jobs, predefined jobs, and rules.
The aim of the API is to enable you to perform most tasks that you can currently do through the TrueSight Network Automation GUI or command line utilities. As compared to the SOAP-based APIs (Web Services Java APIs), the REST API provides similar features, though jobs are more fully supported in the REST API. The SOAP-based APIs are still supported, but will be deprecated over time and new features will no longer be added.
You can access API only over HTTPS. This topic explains how to submit your first request to the REST API.
Using the Swagger UI
The TrueSight Network Automation server provides a user-friendly interface to experiment with the REST API calls, known as the Swagger UI. Calls to the REST API can be made from any scripting or programming language that supports HTTPS, but the Swagger UI can be used from any browser without any programming effort on your part. This section describes how to use the Swagger UI.
To access the Swagger UI
- Start your web browser (see Web-based client system requirements for a list of supported web browsers).
Enter the URL in the following format:
The port number is not required if the product is installed with the default port (for example, 443).
- (Optional) For future reference, bookmark this URL.
This launches the Swagger UI, which enables you to explore and interact with all endpoints in the REST API. The Swagger UI displays the following links:
- All Versions: Contains the following endpoints which are independent of any specific version of the REST API:
- about: Displays the product information and API version.
- token: Enables you to manage authentication tokens.
- Version 3.0: Contains the version 3.0 endpoints to manage various components, as shown in the following figure:
- Version 2.1: Contains the version 2.1 endpoints to manage various components, as shown in the following figure:
- Version 2.0: Contains the version 2.0 endpoints to manage various components, as shown in the following figure:
- Version 1.0: Contains the deprecated version 1.0 endpoints to manage various components, as shown in the following figure:
Authenticating with a token
Requests to every endpoint in the REST API must be made on behalf of a TrueSight Network Automation user. The authentication mechanism is token-based. The Swagger UI lets you generate a token from the credentials of a valid TrueSight Network Automation user who is granted the right to login using web services.
To generate a token
- In the Swagger UI, click the All Versions link.
- Click the token link.
- Under token, click Post.
- In the Parameters section, enter the TrueSight Network Automation user name and password.
- Click Try it out.
A token is now requested in the background. The
access_tokenattribute in the Response Body section contains the generated token, which you can use for authentication in subsequent requests.
To find out more about authentication and tokens, see the Authentication and permissions in the REST API topic.
Calling an endpoint
Now you can make your first explicit API request. This example calls the GET /v2.0/combo_groups endpoint and returns the combo groups belonging to the Default realm.
To call the endpoint
- Expand the "combo groups" category and then click the
- In the filter.realm parameter, enter Default.
- In the Authorization parameter, enter the token in the following format: Bearer token, where the token is the
access_tokenobtained in To generate a token.
- Click Try it out! to call the endpoint.
A successful request will return the combo groups belonging to the Default realm. To understand the results structure, click "Model" in the Response Class section of this endpoint.
If you experience problems calling the endpoint, see the Troubleshooting the REST API topic. Otherwise, you can now experiment with any of the other endpoints.
Calling the API from real clients
The Swagger UI is convenient for experimenting with the REST API. However, for real clients, calls to the API can be made from any scripting or programming language that supports HTTPS. Whatever client language or tool you use to call the REST API, it is recommended you read the related documentation first to see how to construct valid requests and to handle responses.
- REST API versioning
- Authentication and permissions in the REST API
- General principles for using the REST API
- Swagger and the REST API documentation
- Endpoints in the REST API all versions
- Endpoints in the REST API v3.0
- Endpoints in the REST API v2.1 (deprecated)
- Endpoints in the REST API v2.0 (deprecated)
- REST API examples
- Troubleshooting the REST API
- Endpoints in the REST API v1.0 (deprecated)