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.

You can perform actions on the following resources:

An entry on a form
A field on a form
A menu on a form

Important

You must only use the APIs mentioned in this documentation. All other APIs (not mentioned in the documentation) are subject to changes and using them in any process may cause unpredictable results.

Example API call

The following example, you can see 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=authenticationstring

The 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 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 you provide a blank password, the AR System server does not attempt to cross-reference the password.

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

HTTP/1.1 200 OK

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

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:

Resource	Endpoints	Actions
An entry on a form	/entry/{formName}	Create or search all entries on the form.
An entry on a form	/entry/{formName}/{entryId}	Get, modify, and delete a 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.
A menu on a form	/menu/expand	Fetch menu details.

Supported operations

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/{formName}/{entryId}	GET	GET Entry
Get multiple entries	Returns the details of all entries on a form.	/entry/{formName}	GET	GET List Entries With Fields
Retrieve an attachment	Returns an attachment for a particular entry or for the list of entries.	/entry/{formName}/{entryId}/attach/{fieldName}	GET	Not applicable
Retrieve an association	Returns the list of associated entries for a particular entry.	/entry/{formName}/{entryId}/assoc/{associationName}	GET	Not applicable
Get a field metadata information	Returns information about the field metadata for a requested field.	/fields/{formName}/{fieldId}	GET	GET Field
Get multiple fields metadata information	Returns information about the field metadata for multiple fields.	/fields/{formname}	GET	GET list of fields
Get a menu metadata information	Returns the menu properties and its content.	/menu/{MenuName}?menu_criteria=criteria1,criteria2...	GET	GET Menu
Get menu details	Returns the expanded menu content in response.	/menu/expand	POST	GET expanded menu content
Create an entry	Creates new entry on a form.	/entry/{formName}	POST	Create Entry
Merge an entry	Merges an existing entry into a form.	/mergeEntry/{formName}	POST	Merge entry
Modify an entry	Updates a single entry on a form.	/entry/{formName}/{entryId}	PUT	Set Entry
Delete an entry	Deletes an entry on a form.	/entry/{formName}/{entryId}	DELETE	Delete Entry

Success codes

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 is 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.