Important

   

Starting from version 8.9.03, BMC Network Automation is renamed to TrueSight Network Automation. This space contains information about TrueSight Network Automation 8.9.03 and the later service packs for 8.9. For earlier releases, see BMC Network Automation 8.9.

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.

The API follows the REST architectural style, so resources, HTTP verbs, and status codes are used. JavaScript Object Notation (JSON) is used to represent data structures in request and response bodies. The endpoints provided by the API are specified using the Swagger specification language. All endpoints use the OAuth 2.0 protocol for authentication.

Getting started

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

  1. Start your web browser (see Web-based client system requirements for a list of supported web browsers).
  2. Enter the URL in the following format: 
    https://serverName:portNumber/bca-networks/apidocs

    Example

    https://bca-networks-01:443/bca-networks/apidocs

    Note

    The port number is not required if the product is installed with the default port (for example, 443).

  3. (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

  1. In the Swagger UI, click the All Versions link.
  2. Click the token link.
  3. Under token, click Post.
     
  4. In the Parameters section, enter the TrueSight Network Automation user name and password.
  5. Click Try it out.
    A token is now requested in the background. The access_token attribute 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

  1. Expand the "combo groups" category and then click the GET /v2.0/combo_groups endpoint. 
  2. In the filter.realm parameter, enter Default.
  3. In the Authorization parameter, enter the token in the following format: Bearer token, where the token is the access_token obtained in To generate a token.
  4. 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.

Related topics

Was this page helpful? Yes No Submitting... Thank you

Comments