This topic introduces the REST API and Swagger UI.

• Using the Swagger UI
• Authenticating with a token
• Calling an endpoint
• Calling the API from real clients
• Related topics

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 BMC 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 BMC 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 BMC 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

   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 2.0: Contains the version 2.0 endpoints to manage various BMC Network Automation components, as shown in the following figure:
  
• Version 1.0: Contains the deprecated version 1.0 endpoints to manage various BMC Network Automation 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 BMC Network Automation user. The authentication mechanism is token-based. The Swagger UI lets you generate a token from the credentials of a valid BMC 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 BMC 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