The R EST 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:
Clients such as curl, Postman, or BMC TestHttpClient tool can make calls to REST APIs. For information about BMC TestHTTPClient tool, see the knowledge article on BMC Communities TestHttpClient - Command line tool to test HTTP(S) services
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 host: www.example.com username=SomeUser&password=mysecret&authString=authenticationstringThe AR System server performs the normal authentication mechanisms to validate the credentials. If the credentials are valid, the AR System 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" : "www.example.com", // 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, the AR System server 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 eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXkThe 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_wW1gFWFOEjXkThe following table lists comment resources for REST operations.
An entry on a form
Fetch field metadata.
The following table lists supported REST operations:
| Operation | Description | URL | HTTP method | Equivalent API call |
|---|---|---|---|---|
| Get an entry | Returns the details of an entry on a form. | /entry// | GET | Get Entry |
| Get multiple entries | Returns the details of all the entries on a form. | /entry/ | GET | Get List Entries With Fields |
| Retrieve an attachment | Returns an attachment for a particular entry or for the list of entries. | /entry///attach/ | GET | Not applicable |
| Retrieve an association | Returns the list of associated entries for a particular entry. | /entry///assoc/ | GET | Not applicable |
| Get a field metadata information | Returns information about field metadata for requested field. | /fields// | GET | Get Field |
| Get multiple fields metadata information | Returns information about multiple fields' metadata. | /fields/ | GET | Get list of fields |
| Get a menu metadata information | Returns the menu properties and its content. | /menu/?menu_criteria=criteria1,criteria2. | GET | Get Menu |
| Get menu details | Returns the expanded menu content in response. | /menu/expand | POST | Get expanded menu content |
| Creatie an entry | Creates new entry on the form. | /entry/ | POST | Create Entry |
| Merge an entry | Merges an existing entry into a form. | /mergeEntry/ | POST | Merge entry |
| Modify an entry | Updates a single entry on a form. | /entry// | PUT | Set Entry |
| Delete an entry | Deletes an entry on a form. | /entry// | DELETE | Delete Entry |
When responding to requests, the REST API uses some of the HTTP status codes. The following table lists the status codes that are returned. Each operation specifies the response code you receive on successful calls or errors.
| Code | Name | Usage |
|---|---|---|
| 200 | OK | 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. |
| 201 | Created | The response used when you create new resources. REST includes the Location header in the response body, which denotes where the new resource is found. |
| 204 | No Content | A response that is similar to code 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.