Atlassian REST API Design Guidelines version 1

Atlassian

API Lifecycle

Versioning

How to handle API versioning

Governance

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

Collection Resources

Collection

What is a collection (set) of resources

Pagination

How to retrieve a range of resources in a collection

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

Data

Data format

which data format use

HTTP Methods

PUT

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.

DELETE

The DELETE method deletes the specified resource.

HTTP Protocol

Caching

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

201 Created

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

204 No Content

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

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.

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.

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

Hypermedia (write)

How to use hypermedia to write data

Hypermedia

How to use hypermedia

Hypermedia (read)

How to use hypermedia to read data

Resources

Dereference Relationships

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

Delete resource

How to delete resources

URL format

How to design URLs

Update resource

How to update a resource

Resource

General informations about resources

Security

Security

Security concerns