API Design Guide

Australian Digital Transformation Office

API Design

Global design

General considerations on API design

API Lifecycle

Versioning

How to handle API versioning

Governance

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

Collection Resources

Pagination

How to retrieve a range of resources in a collection

Error handling

Error format

How to provide information about errors

HTTP Methods

POST

The POST method requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI. The data POSTed might be, for example, an annotation for existing resources; a message for a bulletin board, newsgroup, mailing list, or comment thread; a block of data that is the result of submitting a web form to a data-handling process; or an item to add to a database.

HEAD

The HEAD method asks for a response identical to that of a GET request, but without the response body. This is useful for retrieving meta-information written in response headers, without having to transport the entire content.

HTTP methods

General information about HTTP methods usage

GET

The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should have no other effect.

DELETE

The DELETE method deletes the specified resource.

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.

HTTP Protocol

Content negociation and media types

How to describe your API data format and/or propose different formats (like json, yaml, xml atom, …)

HTTP Status Success

201 Created

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

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.

HTTP Status User Error

405 Method Not Allowed

A request method is not supported for the requested resource; for example, a GET request on a form which requires data to be presented via POST, or a PUT request on a read-only 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.

Hypermedia

Hypermedia

How to use hypermedia

Hypermedia (read)

How to use hypermedia to read data

Hypermedia (write)

How to use hypermedia to write data

Miscellaneous

Developer experience

How to take care of developer experience (DX)

CORS

How to deal with CORS

Documentation

How to produce and/or propose API documentation

Resources

Relationships

How to define and use relations between resources

URL format

How to design URLs

Security

Security

Security concerns

Data privacy

Data privacy concerns