Requests and Responses

This section outlines the conventions used throughout the REST API, including the request and response formats, standard headers, and resource versioning.

Request and Response Formats

All API requests and responses use the JSON (JavaScript Object Notation) format, which is a lightweight, human-readable data interchange format. The request and response bodies should be structured as JSON objects.

Request Format

All API requests should include the following headers:

• 'Content-Type': Set this header to 'application/json' to indicate that the request body is formatted as JSON.

• 'Authorization': Include sessionid or API token for authentication.

For more information, see Creating a Request.

Response Format

The API responses will include the 'Content-Type' header set to 'application/json' to indicate that the response body is formatted as JSON. The response will also include information about the resource requested, as well as any diagnostic information about the request itself. For more information, see Receiving a Response .

eTags

The REST API uses eTags (entity tags), to prevent multiple users from editing the same item simultaneously. The eTags are an integer values that represent a specific version of a specific resource. When a user attempts to update an item, ChangeGear checks the eTag provided by the user against the eTag stored for that specific resource. If the eTags match, then the resource is updated. If the eTag sent does not match the eTag for that entity, the update fails. This ensures that updates are always done against the most recent version of the entity. If you want to update an item using the REST API, you need to present the correct eTag to the server for validation. For more information on eTags, see Update an Item in the Entity API.