RESTFul API Guidelines

API counts

How many endpoints/resources in an API?

• Limit of Resources

  a typical range of resources for a well-designed API is between 4 and 8

Global design

General considerations on API design

• Design Principles

Governance

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

• API First
• Deprecation
• API Discovery

Updates and Versioning

How to handle API updates and versioning

• Compatibility
• Don’t Break Backward Compatibility
• Avoid Versioning
• Use Media Type Versioning

Asynchronicity

How to handle long operations

• Events

Notifying API consumers

How to send events or notifications to API consumers

• Events

Filtering

How to select some resources in a collection

• Use Conventional Query Strings

  q — default query parameter

Pagination

How to retrieve a range of resources in a collection

• Use Conventional Query Strings

  limit, cursor, offset

• Pagination

Retrieve a collection

How to get a collection or resources

• GET

  reads a resource or set of resource instances

Sorting a collection

How to sort a collection of resources

• Use Conventional Query Strings

  sort — comma-separated list of fields to sort

Collection

What is a collection (set) of resources

• Resources

Standards data

Which standard use for values like languages, countries, currencies, …

• Standards could be used for Language, Country and Currency
• Use Standards for Country, Language and Currency Codes

Date and Time

How to deal with date and time data

• Date property values should conform to RFC 3399
• Time durations and intervals could conform to ISO 8601
• Use Standard Date and Time Formats
• HTTP headers

  Use the HTTP date format defined in RFC 7231

Null data

How to deal with null data

• Property values
• Null values should have their fields removed
• Boolean property values must not be null
• Empty array values should not be null

Data format

which data format use

• Property Values
• Date property values should conform to RFC 3399
• Time durations and intervals could conform to ISO 8601
• Data Formats
• Common Data Objects

Error format

How to provide information about errors

• Providing Error Documentation
• Use Problem JSON

DELETE

The DELETE method deletes the specified resource.

• DELETE

GET

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

• GET

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.

• HEAD

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.

• OPTIONS

PATCH

The PATCH method applies partial modifications to a resource.

• PATCH

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.

• POST

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.

• PUT

HTTP methods

General information about HTTP methods usage

• Use HTTP Methods Correctly
• HTTP Methods must Fulfill Safeness and Idempotency Properties

Caching

How to use and provide relevant caching informations

• Support the ETag Header

Content negociation and media types

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

• Use Media Type Versioning
• Modify the Content-Type for Embedded Resources
• Use Application-Specific Content Types

HTTP Headers

How to use standard or custom HTTP headers

• You Must Hyphenate HTTP Headers
• Prefer Hyphenated-Pascal-Case for HTTP header Fields
• Use Standardized Headers
• Use 429 with Headers for Rate Limits
• Do Not Use Link Headers with JSON entities
• HTTP headers

  Use the HTTP date format defined in RFC 7231

• Common Headers
• Proprietary Headers
• Add a Warning Header to Responses

HTTP Statuses

General information about HTTP statuses usage

• Use Meaningful HTTP Status Codes

HTTP protocol

General informations about HTTP protocol

• HTTP

301 Moved Permanently

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

• Redirection Codes

302 Found

Common way of performing URL redirection. An HTTP response with this status code will additionally provide a URL in the location header field. The user agent (e.g. a web browser) is invited by a response with this code to make a second, otherwise identical, request to the new URL specified in the location field.

303 See Other

The response to the request can be found under another URI using a GET method. When received in response to a POST (or PUT/DELETE), the client should presume that the server has received the data and should issue a redirect with a separate GET message.

• Redirection 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.

• Redirection Codes

500 Internal Server Error

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

• Server Side Error Codes

501 Not Implemented

The server either does not recognize the request method, or it lacks the ability to fulfill the request. Usually this implies future availability (e.g., a new feature of a web-service API).

• Server Side Error Codes

503 Service Unavailable

The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.

• Server Side Error 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.

• Success Codes

201 Created

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

• Success 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.

• Success Codes

204 No Content

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

• Success Codes

400 Bad Request

The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, too large size, invalid request message framing, or deceptive request routing).

• Client Side Error Codes

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.

• Client Side Error Codes

403 Forbidden

The request was a valid request, but the server is refusing to respond to it. The user might be logged in but does not have the necessary permissions for the resource.

• Client Side Error Codes

404 Not Found

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

• Client Side Error Codes

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.

• Client Side Error Codes

406 Not Acceptable

The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.

• Client Side Error Codes

408 Request Timeout

The server timed out waiting for the request. According to HTTP specifications: The client did not produce a request within the time that the server was prepared to wait. The client MAY repeat the request without modifications at any later time.

• Client Side Error Codes

409 Conflict

Indicates that the request could not be processed because of conflict in the request, such as an edit conflict between multiple simultaneous updates.

• Client Side Error Codes

412 Precondition Failed

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

• Client Side Error Codes

415 Unsupported Media Type

The request entity has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format.

• Client Side Error Codes

423 Locked

The resource that is being accessed is locked.

• Client Side Error Codes

428 Precondition Required

The origin server requires the request to be conditional. Intended to prevent the lost update problem, where a client GETs a resource’s state, modifies it, and PUTs it back to the server, when meanwhile a third party has modified the state on the server, leading to a conflict.

• Client Side Error Codes

429 Too Many Requests

The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.

• Client Side Error Codes
• Use 429 with Headers for Rate Limits

Hypermedia (read)

How to use hypermedia to read data

• Use Pagination Links Where Applicable
• Use a well-defined subset of HAL
• Use Custom Link Relations
• Do Not Use Link Headers with JSON entities

Hypermedia

How to use hypermedia

• Use Pagination Links Where Applicable
• Hypermedia
• Use a well-defined subset of HAL
• Do Not Use Link Headers with JSON entities

Documentation

How to produce and/or propose API documentation

• Provide External Documentation
• Reflect Deprecation in API Definition

Performance and bandwidth

How to deal with high traffic or consumers with low bandwith

Query parameters

How to use query parameters

• Query parameters must be snake_case (never camelCase)
• Use Conventional Query Strings

Language

Which language(s) use when designing an API

• Write APIs in U.S. English

Case

Which case (lowercase, camelCase, …) to use and when

• Property names must be snake_case

Naming

How to name things

• Property naming
• API Naming
• Use Domain-Specific Resource Names

Action resource

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

• Avoid Actions — Think About Resources

Create resource

How to create resources

• POST

  creates a resource instance

Delete resource

How to delete resources

• DELETE

  deletes a resource instance

Relationships

How to define and use relations between resources

• Use a well-defined subset of HAL
• Use Custom Link Relations
• Do Not Use Link Headers with JSON entities

Replace resource

How to replace (or update fully) a resource

• PUT

  fully uploads an entity

Dereference Relationships

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

• Use Conventional Query Strings

  embed — to expand embedded entities

• Define useful resources
• Allow Optional Embedding of Sub-Resources
• Modify the Content-Type for Embedded Resources

Retrieve resource partially

How to retrieve partially a resource

• Use Conventional Query Strings

  fields — to retrieve a subset of fields

• Define useful resources
• Support Filtering of Resource Fields

Retrieve resource

How to retrieve a resource

• GET

  reads a resource or set of resource instances

Update resource partially

How to udate partially a resource

• PATCH

  only a specific subset of resource fields are replaced

Update resource

How to update a resource

• PUT
• PATCH

URL format

How to design URLs

• Path segments must be lowercase separate words with hyphens
• Always Pluralize Resource Names
• First Path segment May be /api
• Avoid Trailing Slashes
• Limit of Sub-Resource Levels

Resource

General informations about resources

• resources

Security

Security concerns

• Security
• Secure Endpoints with OAuth 2.0
• Define and Assign Access Rights (Scopes)