Communication and Error Messages - getNEXT Developer Site

URI Structure

getNEXT’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 getNEXT’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 getNEXT 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

getNEXT 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