Atlassian REST API Design Guidelines version 1


API Lifecycle


How to ensure API governance (advertise, consistency, …)

Updates and Versioning

How to handle API updates and versioning

Collection Resources


How to retrieve a range of resources in a collection

  • REST Resources
    Standard Query Parameters in URIs (start-index, max-results)


What is a collection (set) of resources


Data format

which data format use

HTTP Methods


The DELETE method deletes the specified resource.


The PUT method requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI.

HTTP Protocol


How to use and provide relevant caching informations

HTTP Headers

How to use standard or custom HTTP headers

HTTP Statuses

General information about HTTP statuses usage

HTTP Status Redirection

301 Moved Permanently

This and all future requests should be directed to the given URI.

304 Not Modified

Indicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match. In such case, there is no need to retransmit the resource since the client still has a previously-downloaded copy.

HTTP Status Success

200 OK

Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.

201 Created

The request has been fulfilled, resulting in the creation of a new resource.

202 Accepted

The request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs.

204 No Content

The server successfully processed the request and is not returning any content.

HTTP Status User Error

401 Unauthorized

Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource.

404 Not Found

The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.

412 Precondition Failed

The server does not meet one of the preconditions that the requester put on the request.


Hypermedia (read)

How to use hypermedia to read data

Hypermedia (write)

How to use hypermedia to write data


How to use hypermedia


Delete resource

How to delete resources

Dereference Relationships

How to load a resource and its linked resources in one call

Update resource

How to update a resource

URL format

How to design URLs


General informations about resources



Security concerns