Examples of using the REST API to get, update, and delete an entry from a form

You can use the REST API to perform basic operations on entries on forms.

Related topics

Learning-about-the-REST-API

Get a single entry

You can use the GET operation to get an entry from the form. The following table lists details about this GET operation.

URL qualifier

/entry/{formName}/{entryId}

formName - The form for which an entry is to be read. 
entryId - The entry ID.

Method

GET

Headers

Header

Value

Authorization

token

(Optional) X-AR-Client-Type

Client Type ID

(Optional) X-AR-RPC-Queue

RPC queue to which the client calls are routed

(Optional) X-AR-Timeout

Timeout (in seconds) for REST request

Default value —120 seconds

(Optional) X-AR-TR-Core-Id

The core ID in a trace ID

(Optional) X-AR-TR-Counter

The counter in a trace ID

(Optional) X-AR-Trace-Id

The complete trace ID

(Optional) X-AR-TR-Is-Counter-Locked

The lock counter

Parameters

Name

Description

fields

Selects what parts of the JSON document to return
For example, 
fields=values(field name1, field name2)

expand

Expands the related entries (associations).

For more information, see Endpoints-in-AR-REST-API.

Returns

An entry object

All possible error codes

If the request is not successful, one of the following error codes is returned:

  • 400 - Request body is incorrect
  • 403 - Forbidden
  • 404 - Form does not exist
  • 500 - Internal Server Error

For more information, see Error-handling-for-the-REST-API.

Notes

The entry object will contain field values for all data fields to which the user has permission.

Request URL

GET http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000002

Request header

Authorization: AR-JWT eyJhbGciOiJIUzI1NiJ9.
eyJleHAiOjE0MTc2NTM1ODgsInN1YiI6IkFsbGVuIiwibmJmIjoxNDE3NjQ5ODY4LCJpc3MiOi
JXLUNTRUlFUk9FLTI5LmFkcHJvZC5ibWMuY29tIiwianRpI
joiSURHQUFCRFVDMllHSUFONkJGUTJBQUFFUEZBNVFXIiwiX2NhY2hlSWQiOjQ3LCJpYXQiOjE0MTc2NDk5ODh9.
V4LGLcEdwD8V_I4rzoWYYSZmEMA82LBB_lEfz4Xnz9Y

Following is a sample code snippet for the GET operation.

package com.example;

import java.nio.charset.StandardCharsets;

import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class Get {

    public static void main(String[] args) throws Exception {
        String token = args[0];

       // start HTTP GET to get an entry
        CloseableHttpClient httpClient = HttpClients.createDefault();
        HttpGet httpGet = new HttpGet(
               "http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000002");

       // add the token to the header
        httpGet.addHeader("Authorization", "AR-JWT " + token);

       // make the call and print the status
       try (CloseableHttpResponse response = httpClient.execute(httpGet)) {
            HttpEntity entity = response.getEntity();
            String jsonEntry = EntityUtils.toString(entity, StandardCharsets.UTF_8);
            System.out.println(jsonEntry);
        }
    }

}

Response Body

HTTP/1.1 200 OK
Date: Wed, 03 Dec 2014 22:53:46 GMT
Content-Type: application/json
Server: Jetty(8.1.15.v20140411)
{
 "values":{
   "Request ID":"000000000000103",
   "Submitter":"Allen",
   "Create Date":"2014-12-03T22:53:37.000+0000",
   "Assigned To":null,
   "Last Modified By":"chris",
   "Modified Date":"2014-12-03T22:53:37.000+0000",
   "Status":"New",
   "Short Description":"testing 123",
   "Status History":{
     "New":{
       "user":"chris",
       "timestamp":"2014-12-03T22:53:37.000+0000"
     }
   }
 },
 "_links":{
   "self":[
     {
       "href":"http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000103"
     }
    ]
 }
}

Update an entry

You can use the PUT operation to modify an entry on a form. The following table lists details about the PUT operation for updating a single entry on a form.

URL qualifier

/entry/{formName}/{entryId}

formName - The form for which an entry is to be updated. 
entryId - The entry ID.

Method

PUT

Headers

Header

Value

Authorization

token

Content-Type

application/json

(Optional) If-Unmodified-Since

HTTP Date

(Optional) X-AR-Client-Type

Client Type ID

(Optional) X-AR-RPC-Queue

RPC queue to which the client calls are routed

(Optional) X-AR-Timeout

Timeout (in seconds) for REST request

Default value —120 seconds

(Optional) X-AR-TR-Core-Id

The core ID in a trace ID

(Optional) X-AR-TR-Counter

The counter in a trace ID

(Optional) X-AR-Trace-Id

The complete trace ID

(Optional) X-AR-TR-Is-Counter-Locked

The lock counter

Request Body

An entry object in a JSON format

Returns

HTTP status code 204 indicates a successful update.

If the client sends If-Unmodified-Since and the entry is modified since that time, then the entry is not updated and status code 412 is returned.

Errors

If the request is not successful, one of the following error codes are returned:

  • 400 - Request body is incorrect
  • 403 - Forbidden
  • 404 - Form does not exist
  • 500 - Internal Server Error

For more information, see Error-handling-for-the-REST-API.

The following example returns an updated entry in a Simple form.

Request URL

PUT http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000002

Request headers

Authorization: AR-JWT eyJhbGciOiJIUzI1NiJ9.
eyJleHAiOjE0MTc2NTM1ODgsInN1YiI6IkFsbGVuIiwibmJmIjoxNDE3NjQ5ODY4LCJpc3MiOi
JXLUNTRUlFUk9FLTI5LmFkcHJvZC5ibWMuY29tIiwianRpI
joiSURHQUFCRFVDMllHSUFONkJGUTJBQUFFUEZBNVFXIiwiX2NhY2hlSWQiOjQ3LCJpYXQiOjE0MTc2NDk5ODh9.
V4LGLcEdwD8V_I4rzoWYYSZmEMA82LBB_lEfz4Xnz9Y

Content-Length: 59
Content-Type: application/json

Request Body

{
 "values":{
   "Submitter":"Allen",
   "Short Description":"testing 123"
 }
}

The following is a sample code snippet for the PUT operation.

package com.example;

import org.apache.http.StatusLine;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.entity.ContentType;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;

public class Put {

    public static void main(String[] args) throws Exception {
        String token = args[0];

       // start HTTP PUT to modify an entry
        CloseableHttpClient httpClient = HttpClients.createDefault();
        HttpPut httpPut = new HttpPut(
               "http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000002");

       // build the JSON entry
        String json = "{ \"values\" : { ";
        json += "\"Short Description\" : \"updated via REST\"";
        json += " } }";
        httpPut.setEntity(new StringEntity(json, ContentType.APPLICATION_JSON));
        httpPut.addHeader("Authorization", "AR-JWT " + token);

       // make the call and print the status
       try (CloseableHttpResponse response = httpClient.execute(httpPut)) {
            StatusLine status = response.getStatusLine();
            System.out.println(status);
        }
    }

}

Update an entry with attachments

The PUT operation also enables you to modify an attachment for a particular entry or from a list of entries.

URL qualifier

/entry/{formName}/{entryId}

formName - The form for which an entry is to be updated. 
entryId - The entry ID.

Method

PUT

Headers

Header

Value

Authorization

token

Content-Type

multipart/form-data

(Optional) If-Unmodified-Since

HTTP Date

(Optional) X-AR-Client-Type

Client Type ID

(Optional) X-AR-RPC-Queue

RPC queue to which the client calls are routed

(Optional) X-AR-Timeout

Timeout (in seconds) for REST request

Default value —120 seconds

(Optional) X-AR-TR-Core-Id

The core ID in a trace ID

(Optional) X-AR-TR-Counter

The counter in a trace ID

(Optional) X-AR-Trace-Id

The complete trace ID

(Optional) X-AR-TR-Is-Counter-Locked

The lock counter

Request Body

A multipart/form-data entity. Each part of a multipart entity has a name, a Content-Type and the value.

There is one part named as entry with Content-Type as application/json and the value is a JSON entry. There are 0 or more parts with names like attach-{fieldName} with any Content-Type and any value. The name is a prefix indicating that it is an attachment binary data, the part after the hyphen is the name of the attachment field. This updates an entry with attachment data.

Returns

HTTP status code 204 indicates a successful update.

If the client sends If-Unmodified-Since and the entry is modified since that time, then the entry is not updated and status code 412 is returned.

Errors

If the request is not successful, one of the following error codes are returned:

  • 400 - Request body is incorrect
  • 403 - Forbidden
  • 404 - Form does not exist
  • 500 - Internal Server Error

For more information, see Error-handling-for-the-REST-API.

Delete an entry

The DELETE operation enables you to delete an entry from a form. The following table lists details about this DELETE operation.

URL qualifier

/entry/{formName}/{entryId}

formName - The form for which entry is to be deleted.
entryId - The entry ID.

Method

DELETE

Headers

Header

Value

Authorization

token

(Optional) X-AR-Client-Type

Client Type ID

(Optional) X-AR-RPC-Queue

RPC queue to which the client calls are routed

(Optional) X-AR-Timeout

Timeout (in seconds) for REST request

Default value—120 seconds

(Optional) X-AR-TR-Core-Id

The core ID in a trace ID

(Optional) X-AR-TR-Counter

The counter in a trace ID

(Optional) X-AR-Trace-Id

The complete trace ID

(Optional) X-AR-TR-Is-Counter-Locked

The lock counter

Returns

No request body, but HTTP status 204 indicates successful deletion.

All possible error codes

If the request is not successful, one of the following error codes are returned:

  • 403 - Forbidden
  • 404 - Form does not exist
  • 500 - Internal Server Error

For more information, see Error-handling-for-the-REST-API.

Notes

You can also use the option FORCE to force delete all the list of entries, for example, ?options=FORCE.

The following example allows you to delete an entry from the form.

Request URL

DELETE http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000002

Request header

Authorization: AR-JWT eyJhbGciOiJIUzI1NiJ9.
eyJleHAiOjE0MTc2NTM1ODgsInN1YiI6IkFsbGVuIiwibmJmIjoxNDE3NjQ5ODY4LCJpc3MiOi
JXLUNTRUlFUk9FLTI5LmFkcHJvZC5ibWMuY29tIiwianRpI
joiSURHQUFCRFVDMllHSUFONkJGUTJBQUFFUEZBNVFXIiwiX2NhY2hlSWQiOjQ3LCJpYXQiOjE0MTc2NDk5ODh9.
V4LGLcEdwD8V_I4rzoWYYSZmEMA82LBB_lEfz4Xnz9Y

Following is a sample code snippet for the DELETE operation.

package com.example;

import org.apache.http.StatusLine;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpDelete;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;

public class Delete {

    public static void main(String[] args) throws Exception {
        String token = args[0];

       // start HTTP DELETE to delete an entry
        CloseableHttpClient httpClient = HttpClients.createDefault();
        HttpDelete httpDelete = new HttpDelete(
               "http://localhost:8008/api/arsys/v1/entry/SimpleForm/000000000000002");

       // add the token to the header
        httpDelete.addHeader("Authorization", "AR-JWT " + token);

       // make the call and print the status
       try (CloseableHttpResponse response = httpClient.execute(httpDelete)) {
            StatusLine status = response.getStatusLine();
            System.out.println(status);
        }
}
}

Response Body

HTTP/1.1 204 No Content
Date: Wed, 03 Dec 2014 22:38:14 GMT
Server: Jetty(8.1.15.v20140411)

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*