REST API

The system REST API accepts and returns JSON.

To use the REST API, you need a user account that has permission to perform actions in system. For information on assigning permissions to users, see Roles.

Requesting an access token

Once you have a user account, you need to request an authentication token from the system. To do this, you send an HTTP POST request to the /auth/oauth endpoint. Here's an example using the cURL command-line tool:

curl -ik -X POST https://<system-hostname>:8000/auth/oauth/ \
-d grant_type=password \
-d username=<your-username> \
-d password=<your-password> \
-d scope=* \
-d client_secret=hci-client \
-d client_id=hci-client \
-d realm=<security-realm-name-for-an-identity-provider-added-to-system>

In response to this request, you receive a JSON response body containing an access_token field. The value for this field is your token. For example:

{"access_token" : "eyJr287bjle..."

Notes:   •To get a list of security realms for the system, send an HTTP GET request to the /setup endpoint. For example, to do this with cURL: curl -X GET --header 'Accept: application/json' 'https://cluster110f-vm1.lab.archivas.com:<admin-app-port>/api/admin/setup' For information on configuring security realms, see Adding identity providers. •To get an access token for the local admin user account, you can omit the realm option for the request, or specify a realm value of Local.

Submitting your access token

You need to specify your access token as part of all REST API requests that you make. You do this by submitting an Authorization header along with your request. Here are some examples using cURL:

•For the administrative API:

curl -X GET --header "Accept:application/json" https://<system-hostname>:<admin-app-port>/api/admin/instances --header "Authorization: Bearer <your-token>"

•For the search API:

curl -X GET --header "Accept:application/json" https://<system-hostname>:<search-app-port>/api/indexes --header "Authorization: Bearer <your-token>"

system provides a web-based documentation page on which you can view all supported REST API methods, including the request bodies, request URLs, response bodies, and return codes for each. You can also use this page to run each REST API method.

Viewing the API documentation

To view the REST API documentation, in the Administration App, click on the help icon (). Then:

•To view the administrative REST API, click on Admin API.

•To view the API used for performing searches, click on Search API.

Making requests

You can use the REST API page to experiment with the system REST API.

Note: Any requests you submit on the REST API page take effect on the system.

To use the REST API page to run a method:

1.Click on the row for the method you want.

2.If the method you want requires that you specify a UUID:

a.Click on the row for the GET method for the resource type that you want.

For example, if you want to edit an index collection, to learn the UUIDs of all index collections in the system, go to the GET /indexes method.

b.Click on the Try it Out! button.

c.In the JSON response body, copy the value for the uuid field for the resource that you want.

3.If the method you want requires that you specify a request body:

a.In the Parameters section, under Model Schema, click inside the JSON text box.

The JSON text is added to the Value field.

b.Edit the JSON in the Value field.

4.Click on the Try it out! button.

When an API request fails, the API returns:

•An HTTP status code

•Conditionally, asystem-specific error code

•A JSON-formatted error response body

HTTP status codes

This table describes the typical reasons why these HTTP status codes are returned. For information on the status codes for a particular method, view the system REST API web interface (see Viewing and using REST API methods).

Status code	Description
400 (Bad Request)	The request body contains one or more of these: •An invalid entry •An invalid value for an entry •Invalidly formatted JSON If the request includes a UUID, the UUID may be invalidly formatted.
403 (Forbidden)	You do not have permission to perform the request.
404 (File not found)	The resource you are trying to retrieve or edit cannot be found.
409 (Conflict)	The resource you are trying to create already exists.
500 (Server Error)	The system experienced an error.

System-specific error codes

Some API requests return system-specific error codes in addition to an HTTP status code. These error codes are listed in the errorCodes field in the JSON response body. This table describes these error codes.

Error code	Description
4000	SSL certificate not trusted.

JSON response body

REST API error responses have this format:

{
    "statusCode": <HTTP-status-code>,
    "errorCode": <system-specific-error-code>,
    "errorMessage": <message>,
    "errorProperties": [
        {
            "name": <error-property>,
            "message": <error-property-message>
        }
    ]
}