This documentation supports the 23.3 version of BMC Helix Innovation Suite (AR System and BMC Helix Innovation Studio).

To view an earlier version, select the version from the Product version menu.

General principles for using the REST API

The API follows the REST architectural style, hence, resources, HTTP verbs, and status codes are used. JSON is used for request and response bodies. The endpoints provided by the API are specified using the Swagger specification language.

The following principles are common to the endpoints provided by the AR SystemREST API.

Endpoint verbs

Endpoints use the following verbs consistently:

VerbPurpose
GETRetrieve a single resource, or collection of resources.
POSTCreate a new resource.

PUT

Update a resource, specifying the required target state of all fields.

As appropriate for the endpoint, any omitted field is reset to the default values or deleted.

DELETEDelete a resource.

Input encoding

When constructing the URL for an endpoint that contains a dynamic portion (either in the path or in the query string), make sure that you encode the characters that are not permitted in a URL.

For example: The URL http://server name:port/api/arsys/v1/entry/User/formName?q=('Request ID'="entryID") is interpreted as http://server name:port/api/arsys/v1/entry/User/formName?q=%28%27Request%20ID%27%3D%22entryID%22%29 

When using the GET operation to fetch entries from a form through any REST client, URL parameters may be required. Examples of URL parameters are qualification (q), fields, limit, and sort. While using any of these parameters with a request URL, make sure that you encode them correctly and then use them in the request; else, results may not be as expected.

To encode URL parameters, use any third-party tool or site such as https://www.w3schools.com/html/html_urlencode.asp Open link , where non-encoded URL parameters can be converted into an encoded URL parameter string. Use these encoded parameters to send a REST request. 

For example: To send a qualification on a form:

 'Incident Number' = "INC000000000701"

It should be encoded and sent as:

%27Incident+Number%27+%3D+%22INC000000000701%22

For more information about how AR System integrates using REST APIs and web services, watch the following video (4:07). 

 https://youtu.be/d-AqmDlQPFI

REST API format

The REST API uses the base URI for the web service; for example, https://localhost:port/api/{namespace}/{version}.

The root URL path for REST API in AR System is as follows:

https://localhost:port/api/arsys/v1

Any partial URL (For example: /entry/{formName}) referred to in the documentation are assumed to have this prefix.

JSON format

JSON is used for both request and response bodies. If you are editing JSON request bodies manually, you must  escape Open link  any reserved characters in your strings.

URLs in responses

Several POST endpoints create a new resource, which you can retrieve by using the REST API. In these cases, the response to the POST request contains a "uri" field, containing the URL of the newly created resource. 

For example:

package com.example;
 
import org.apache.http.Header;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
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 Post {
 
    public static void main(String[] args) throws Exception {
        String token = args[0];
 
        // start HTTP POST to create an entry with fields parameter
        CloseableHttpClient httpClient = HttpClients.createDefault();
        HttpPost httpPost = new HttpPost("http://localhost:8008/api/arsys/v1/entry/SimpleForm?fields=values(field1, field2)");
 
        // build the JSON entry
        String json = "{ \"values\" : { ";
        json += "\"Submitter\" : \"Allen\", ";
        json += "\"Short Description\" : \"testing 123\"";
        json += " } }";
        httpPost.setEntity(new StringEntity(json, ContentType.APPLICATION_JSON));
        httpPost.addHeader("Authorization", "AR-JWT " + token);
 
        // make the call and print the Location
        try (CloseableHttpResponse response = httpClient.execute(httpPost)) {
            Header locationHeader = response.getFirstHeader("Location");
            System.out.println(locationHeader.getValue());
            HttpEntity entity = response.getEntity();
        // Read the contents of an entity and return it as a String.
            String content = EntityUtils.toString(entity);
            System.out.println(content);
        }
    }
 
}

Error responses

Failed requests are indicated by the  HTTP status codes: 4xx(client error) or 5xx(server error.

In some cases the response body might also contain an object that contains details of the error, with the following fields:

FieldMeaning
codeThe HTTP status code.
messageA description of what went wrong.

Do not rely on error responses containing a body. In particular, authentication or permission failures often have empty bodies to avoid information leakage to the caller. Here is an example request, resulting in the response 400 Bad Request

http://<local host>:8008/api/arsys/v1.0/fields/User/?field_type=A&field_ids=1
[ 
  {  
  "messageType": "ERROR",
  "messageText": "Unexpected use of query parameter", 
  "messageNumber": 8043,
  "messageAppendedText": "Either field_ids or field_type can be provided. Both set are not allowed." 
   }
]
Was this page helpful? Yes No Submitting... Thank you

Comments