Phased rollout


This version of the software is currently available only to early adopter SaaS customers as the first step in our phased rollout. Click here to view an earlier version.

Overview of the REST API

The REST API uses a resource to perform HTTP operations. A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it. Actions can be performed on the following resources:

  • An entry on a form
  • A field on a form
  • A menu on a form
Related topics

The REST API references

Access and authentication for the REST API Open link

Example API call

The following example shows how a client creates a POST call and passes the user name, password, and authString in the Request headers using the /x-www-form-urlencoded content type:

POST /api/jwt/login HTTP/1.1

BMC Helix ITSM performs the normal authentication mechanisms to validate the credentials. If the credentials are valid, the AR Server generates a JSON Web Token (JWT). You can attempt a REST API call if you have a token. A single JWT token is valid for an hour. You can use a single token across multiple AR System servers that are in the same server group.

// comments not actually included, added for clarity
    // the username
    "sub" : "SomeUser",
    // the Server-Connect-Name of the AR Server who issued the token
    "iss" : "",
    // the UNIX time when the token was issued
    "iat" : 1408774310,
    // 2 minutes before "iat", to account for clock skew between servers
    "nbf" : 1408777790,
    // the UNIX time when the token expires, the duration being a configurable value (probably between 1 minute and 12 hours)
    "exp" : 1408777910,
    // a custom claim, the cache ID
    "_cacheId" : 13


If the user provides a blank password, BMC Helix ITSM does not attempt to cross-reference the password.

The JWT is signed and base64 encoded string, and is sent back as a response body to the HTTP request:

HTTP/1.1 200 OK

The client receives the token and uses it in all subsequent REST API calls through the Authorization header using the AR-JWT schema:

GET /api/arsys/v1/entry/SomeForm HTTP/1.1
Authorization: AR-JWT eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Supported resources

The following table lists comment resources for REST operations.


An entry on a form

/entry/{formName}Create or search all entries on the form.
/entry/{formName}/{entryId}Get, modify, and delete that particular entry.
A field on a form/fields/{formName}/{fieldId}

Fetch field metadata.

A menu on a form/menu/{MenuName}?menu_criteria=criteria1,criteria2...Fetch menu metadata.
/menu/expandFetch menu details.

Supported operations

The following table displayed common parameters for REST operations: 

OperationDescriptionURLHTTP methodEquivalent API call
Get an entryReturns the details of an entry on a form./entry/{formName}/{entryId}GETGet Entry
Get multiple entriesReturns the details of all the entries on a form./entry/{formName}GETGet List Entries With Fields
Retrieve an attachment using REST APIReturns an attachment for a particular entry or for the list of entries. /entry/{formName}/{entryId}/attach/{fieldName}GETnot applicable
Retrieve an association using REST APIReturns the list of associated entries for a particular entry. /entry/{formName}/{entryId}/assoc/{associationName}GETnot applicable
Get a field metadata informationReturns information about field metadata for requested field./fields/{formName}/{fieldId}GETGet Field
Get multiple fields metadata informationReturns information about multiple fields metadata./fields/{formname}
GETGet list of fields
Get a menu metadata informationReturns the menu properties and its content./menu/{MenuName}?menu_criteria=criteria1,criteria2...
GETGet Menu
Get menu detailsReturns the expanded menu content in response./menu/expandPOSTGet expanded menu content
Create an entry using REST APICreates new entry on the form./entry/{formName}POSTCreate Entry
Merge an entry using REST APIMerges an existing entry into a form./mergeEntry/{formName}POSTMerge entry
Modify an entry Updates a single entry on a form./entry/{formName}/{entryId}PUTSet Entry
Delete an entryDeletes an entry on a form./entry/{formName}/{entryId}DELETEDelete Entry

For more information about these operations, see the same table in  Overview of the REST API Open link in the AR System documentation.

HTTP status codes

When responding to requests, the REST API uses some of the HTTP status codes. The following table gives a summary of the status codes that are returned. Each operation specifies the response code you receive on successful calls or errors. 

200OKThis code is the default response for a successful API call. If the documentation does not specify an HTTP status code that is returned on a successful call, it is assumed to be 200.
201CreatedThis code is used when you create new resources. REST includes the Location header in the response body, which denotes where the new resource is found.
204No ContentThis code is similar to 200, but with no response body. This code is commonly used for DELETE operations.

For a list of error codes, see  Error handling for the REST API Open link  in the AR System documentation.

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