Operations on entry objects

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. The following are resources on which the actions are performed:

the form
an entry on a form

Type	URL	Actions
form	/entry/{formName}	Performs HTTP requests on just the form and allows you to create or search all entries on the form.
an entry on a form	/entry/{formName}/{entryId}	Performs HTTP requests on an entry on a form and allows you to get, modify, and delete that particular entry.

This section provides the following topics:

Supported operations

The following table explains the HTTP methods used in BMC Remedy AR System:

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 the entries on a form.	/entry/{formName}	GET	Get List Entries With Fields
Get an attachment	Returns an attachment for a particular entry or for the list of entries.	/entry/{formName}/{entryId}/attach/{fieldName}	GET	not applicable
Get an association	Returns the list of associated entries for a particular entry.	/entry/{formName}/{entryId}/assoc/{associationName}	GET	not applicable
Create an entry	Creates new entry on the 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

Common parameters

The following table explains the list of parameters commonly used in the REST operations:

Name	Description	Example
fields	Returns parts of the entry object (fields and association links). You can use values() with a comma-separated list of field names inside the parentheses to return only those field values. You can use assoc to get links to all related entries. You can also use assoc() with a comma-separated list of association names inside the parenthesis to get links following those associations.	`fields=values(Status,Notes)` `fields=assoc` `fields=assoc(Worklog,Testlog)` `fields=values(Status,Notes),assoc(WorkLog)`
q	Sends a search qualification. Use a URL-encoded value for the search qualification.	`q=%27Submitter%27%20%3D%20%22Allen%22` `%27Submitter%27%20%3D%20%22Allen%22` is the URL-encoded version of 'Submitter' = "Allen" to find entries that Allen has submitted.
offset	Specifies the number (non-negative integer) of entries to offset the results by. Used for paginating results.	`offset=50` Offsets the result by 50 entries
limit	Specifies the number (non-negative integer) of entries to limit the results by. Used for paginating results.	`limit=10` Gets no more than 10 entries
expand	Expands the related entry (associations). You can use assoc() with a comma-separated list of association names inside the parenthesis to embed copies of the related entries following those associations.	`expand=assoc(WorkLog)` returns embedded copies of the work log entries for this entry, following the WorkLog association
sort	Sorts results on a search by field name and direction. Multiple field names can be used, separated by commas. The direction is indicated by appending .asc for ascending and .desc for descending after the field name.	`sort=Status.asc,Create Date.desc` Sorts first by Status in ascending order and then by Create Date in descending order.
option	Use in delete entry calls. Allowed values: NONE FORCE — Use this option if you want to delete individual entries that are not retrieved from the join schema. NOCASCAE — Use this option if you do not want to run the workflow when the delete entry operation is called.	`options=NOCASCADE&options=FORCE`

HTTP status codes

When responding to requests, the REST API uses some of the HTTP status codes. The following table gives a summary of the different status codes that are returned. Each operation specifies the response code you receive on successful calls or errors.

Code	Name	Usage
200	OK	This code is the default response for a successful API call. If the documentation does not specify a HTTP status code that is returned on a successful call, it is assumed to be 200.
201	Created	This code 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	This code is similar to 200, but with no response body. This code is commonly used for DELETE operations.
400	Bad Request	This code is used if the request body is not correct. For example, a JSON document is sent but it is not the correct format or the client sends a date value in the wrong format.
401	Unauthorized	This code is used if the user is not authenticated.
403	Forbidden	This code is used when the call is authenticated, but the user does not have access to the resource. For example, an entry operation on a form to which the user does not have permission.
404	Not found	This code is used when a resource does not exist.
500	Internal Server Error	This code is the default response for any error that occurs when an API call is being processed.

JSON representation of an error

The HTTP status codes are the response that classify the failure of the request. The HTTP status code is provided in the response header, whereas, the additional information for the error is provided in the response body. The following code sample represents the format of the message you receive when you encounter an error:

[
    {
       "messageType": "ERROR",
       "messageText": "Form does not exist on the server",
       "messageAppendedText": "someFormName",
       "messageNumber": 303
    }
    ...
]

Name	Data type	Description
messageType	String	Type of message returned. For example, OK, ERROR, WARNING, FATAL, BAD STATUS.
messageText	String	The actual text of the error message.
messageAppendedText	String	The text that augments the error message.
messageNumber	Integer	The AR error number associated with the error message.

Operations on entry objects

Supported operations

Common parameters

HTTP status codes

JSON representation of an error

Related topics

Comments