Atlassian REST API Design Guidelines version 1

API Lifecycle

Versioning

How to handle API versioning

Version Control for APIs

Governance

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

Using these Guidelines
We strongly recommend that someone who is familiar with these guidelines should review your REST API code
Version Control for APIs
When to Change the Version

Collection Resources

Collection

What is a collection (set) of resources

REST Resources
URI Structure
REST Resources
Collections of Entities

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

REST Resources
Representations (Content Types) of Entities
Appendix B: Basic Data Types

HTTP Methods

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.

Concurrency

DELETE

The DELETE method deletes the specified resource.

Concurrency

HTTP Protocol

Caching

How to use and provide relevant caching informations

REST Resources
Version Control for Entities
Caching

HTTP Headers

How to use standard or custom HTTP headers

REST Resources
Entities SHOULD be served with an ETag header.
Caching
ETag, If-None-Match

HTTP Statuses

General information about HTTP statuses usage

Appendix A: Response Codes

HTTP Status Redirection

301 Moved Permanently

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

Appendix A: Response Codes

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.

Appendix A: Response Codes

HTTP Status Success

201 Created

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

Appendix A: Response Codes

204 No Content

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

Appendix A: Response Codes

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.

Appendix A: Response Codes

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.

Appendix A: Response Codes

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.