Thoughts on RESTful API Design

Red Hat

Asynchronicity

Asynchronicity

How to handle long operations

Notifying API consumers

How to send events or notifications to API consumers

Collection Resources

Retrieve a collection

How to get a collection or resources

Pagination

How to retrieve a range of resources in a collection

Collection

What is a collection (set) of resources

Data

Data format

which data format use

HTTP Methods

HTTP methods

General information about HTTP methods usage

OPTIONS

The OPTIONS method returns the HTTP methods that the server supports for the specified URL. This can be used to check the functionality of a web server by requesting ‘*’ instead of a specific resource.

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.

PATCH

The PATCH method applies partial modifications to a resource.

DELETE

The DELETE method deletes the specified resource.

GET

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

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.

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 Headers

How to use standard or custom HTTP headers

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.

Hypermedia

Hypermedia

How to use hypermedia

Hypermedia (write)

How to use hypermedia to write data

  • Forms
    ... without referring to external documentation, an API user does not know what data to provide to operations that take input.

Hypermedia (read)

How to use hypermedia to read data

Miscellaneous

Guiding inputs

How to help consumers or end user to input relevant data

  • Forms
    ... without referring to external documentation, an API user does not know what data to provide to operations that take input.

Documentation

How to produce and/or propose API documentation

  • Forms
    ... without referring to external documentation, an API user does not know what data to provide to operations that take input.

Resources

Create resource

How to create resources

Action resource

How to use action resource (e.g. resources like /cancel or /approve)

Delete resource

How to delete resources

Resource ID

What is a resource ID and/or how it’s built

Update resource partially

How to udate partially a resource

Relationships

How to define and use relations between resources

Retrieve resource

How to retrieve a resource

Update resource

How to update a resource

URL format

How to design URLs

Resource

General informations about resources