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.

Clients such as curl, Postman, or BMC TestHttpClient tool can make calls to REST APIs. For information on how to get, update or delete an entry using the BMC TestHTTPClient tool, see the knowledge article on BMC Communities TestHttpClient - Command line tool to test HTTP(S) services Open link .

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=entryId1,entryId2).
expand	Expands the related entries (associations).

For more information, see Common parameters.

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 HTTP status codes.

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 HTTP status codes.

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 HTTP status codes.

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 HTTP status codes.

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)

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

Get a single entry

Update an entry

Update an entry with attachments

Delete an entry

Related topic

Comments