Using the REST API

This chapter provides basic information about how to use the REST API.

Authorization

The REST API uses JSON Web Token (JWT) for authorization.

You can obtain a token by making a POST REST call to the endpoint: <base_url>/authenticate with the payload that specifies the credentials and client context. The following example demonstrates the content of such a payload:

{ "username": "admin", "password": "admin", "clientContext": 1 }

The service then returns a token that has to be used for future REST calls. The token should be added in the header of a request in the following manner:

key: Authorization, value: Bearer TOKEN

TOKEN is the token returned by the authorization service.

Note All REST calls require a token except the following ones:

  • get sample data model
  • get sample topology query

For an example about how to obtain a token, see A Usage Example.

REST API Endpoint

You must specify an endpoint when you make a REST call. An endpoint includes the following parts:

<base_url><resource_url>

  • <base_url>: The URL of where the REST API is deployed.

    If you deploy the rest-api.war package under the webapps folder of Tomcat, the base URL is:

    http(s)://<IP_or_FQDN_of_Tomcat>/rest-api

  • <resource_url>: See the URL section of each call in Reference.

Tips

  • The logs produced by the REST API are in the following file:

    • Embedded: <UCMDB_Server_Home>/runtime/log/rest_api.log
    • Standalone: $CATALINA_HOME/logs/rest_api.log
  • The REST API prints and consumes every date attribute in the ISO8601 format:

    yyyy-MM-dd'T'HH:mm:ss.SSSZZ