Swagger and the REST API

The endpoints provided by the REST API can be viewed on their own page. However, they are also documented in a more structured way using the Swagger specification language.

The swagger.json file

The Swagger specification of the REST API consists of a file of JSON data called swagger.json. This file includes endpoint URLs, descriptions, request parameters and response structures. Defining the endpoints in this standard, machine-readable format enables the use of automated tools such as interactive documentation and client code generation.

As each version of the REST API has its own list of endpoints, there is one swagger.json file per version. For example, the specification of the endpoints in version 1.0 of the API can be found at:

/api/v1.0/swagger.json

This file is not protected by authentication and can be viewed in a browser.

The Swagger UI

One example of a tool that consumes a Swagger specification is the Swagger UI. This shows a list of endpoints in a web page, enabling users to read about them and, after authentication, submit requests. BMC Discovery 11.1 and later appliances host the Swagger UI and link to it from the Help menu on every page:

Alternatively you can access the Swagger UI directly at:

https://appliance/swagger-ui

The Swagger UI loads the specified swagger.json file and then displays an expandable list of endpoints, grouped by category:

Each endpoint has a Try it out! button which lets you submit a request to it. However, as with all requests to endpoints in the REST API, an authentication token must be supplied in an HTTP header. The Swagger UI automatically adds such a header to every request, once you have supplied a token. To do this, click Authorize in the top right of the Swagger UI page to display the Available Authorizations dialog:

This dialog supports tokens generated by both mechanisms described in the topic Authentication and permissions in the REST API:

• To generate an expiring token from the /api/token endpoint, enter the username and password to use in the OAuth 2.0 section and click Authorize. This returns you to the main Swagger UI page, with a request to /api/token occurring in the background. If this request succeeds, the resulting token is added to every endpoint request you make. Note that after sixty minutes the token will expire and you will need to generate another token.
• To use a permanent token, first generate one from the BMC Discovery Users administration page. Then enter this token in the Api key authorization section of the Authorizations dialog above. As with setting HTTP headers directly, the value of the header field must be in the form "bearer <your_token>". Now click Authorize to return to the main Swagger UI page. The token you entered will now be added to every endpoint request you make.