Communication and Error Messages

URI Structure

TruEdit’s REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The JIRA REST API uses JSON as its communication format, and the standard HTTP methods GET, PUT, POST, and DELETE (see the Resources section for which methods are available for each resource). URIs for TruEdit’s REST API resources have the following structure:

http://host:port/api/api-version/resource-name/:id

Expansion

In order to simplify API responses, the TruEdit REST API uses resource expansion. This means the API will only return parts of the resource when explicitly requested.

You can use the optional minimal query parameter to specify whether you want the expanded resource. For example, appending ?minimal=false to a URI requests the inclusion of all fields for a resource provided in the response. Conversely, appending ?minimal=true to a URI request indicates that a resource in the response would only include the ID and name, for example.

Pagination

TruEdit uses pagination to limit the response size for resources that return a potentially large collection of items. A request to a paged API will result in a results array wrapped in a JSON object with some paging metadata, for example:

{
    "statusCode": 0,
    "errorMessage": null,
    "warnings": null,
    "developerMessage": null,
    "moreInfo": null,
    "results": [
        ...
    ],
    "pageSize": 100,
    "pageNumber": 1,
    "totalItems": 17
}

Clients can use the pageNumber and pageSize query parameters to retrieve the desired number of results.

The pageSize parameter indicates how many results to return per page. Each API may have a different limit for the number of items returned.

The pageNumber parameter indicates which page should be used as the first page in the results.

Important: The response contains a totalItems field which denotes the total number of entities contained in all pages. This number may change as the client requests the subsequent pages. A client should always assume that the requested page can be empty. REST API consumers should also consider the totalItems field to be optional. In cases, when calculating this value is too expensive we may not include this in the response.

Ordering

Some resources support ordering by a specific field. An ordering request is provided in the orderBy query parameter. (See the Resources section for specific methods to see which fields they support and if they support ordering at all.)

Ordering can be ascending or descending. By default, it’s ascending. To specify the ordering use “asc” or “desc” as follows:

?orderBy=name
Order by “name” ascending
?orderBy=name%20asc
Order by “name” ascending
?orderBy=name%20desc
Order by “name” descending

Error Responses

Most resources will return a response body in addition to the status code. Usually, the JSON schema of the entity returned is the following:

{
    "statusCode": 0,
    "errorMessage": null,
    "warnings": null,
    "developerMessage": null,
    "moreInfo": null,
    "results": [
        ...
    ],
    "pageSize": 100,
    "pageNumber": 1,
    "totalItems": 17
}
The statusCode value is the error/status code, where 0 means success. More details for specific error/status code can be found below.
The errorMessage value is a localized error message, intended for the end-user of the client using the API. It may be null.
The warnings value is a list of warnings (provided as an array of strings); this is used when an API call requested actions on multiple objects and the action failed for at least one of those objects. It may be null.
The developerMessage value is a more technical error message intended for the developer of the client, not the end-user.  It may be null.
The moreInfo value provides a URL to documentation about that error code, again for the developer. It may be null.
To specify the language you want for these messages, please send the “accept-language” header with your request. Please note that we default to English language messages.

Error/Status Codes

Reason Code
No error; success. 0
Error code for when there is not a more specific error code. 1
Internal server error; indicates a bug or unhandled database or I/O error. 2
Indicates partial success during a batch operation. 3
Generic Error; prompt required. 1000
Miscellaneous authorization problem. 2000
Provided API key was not valid. 2001
The Tenant does not have its public API usage flag enabled. 2002
The Tenant’s API call rate has been exceeded. 2003
The Tenant’s API call rate is nearing its limit. 2004
The user is not active in the Tenant, or the Tenant is at its active user limit, etc. 2005
The session specifies a client type that the user is (no longer) authorized to use; used by internal server, not public API. 2006
The user session has expired or has some other problem. 2007
The user does not have the privilege to perform the requested action. 3000
Indicates the user is not allowed to access the specified Job. 3001
Indicates the user is not allowed to save a global filter or that the specified filter belongs to another user. 3002
The user’s privileges have changed since they logged in. 3003
The user tried to do something that Status Rights don’t permit them to do. 3004
Invalid parameter value supplied. 4000
Generic name conflict. 4001
The request is invalid because it conflicts with an expected type or value. 4002
Generic job state conflict. 5000
Profile hierarchy violation. 5001
Access control conflict. 5002