Design Topics

All topics covered by analyzed Design Guidelines are listed here.

Each topic page lists all references to a specific topic throughout all analyzed guidelines.

API Design

API counts

How many endpoints/resources in an API?

Global design

General considerations on API design

API Lifecycle

Governance

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

Versioning

How to handle API versioning

Asynchronicity

Asynchronicity

How to handle long operations

Notifying API consumers

How to send events or notifications to API consumers

Collection Resources

Collection

What is a collection (set) of resources

Filtering

How to select some resources in a collection

Pagination

How to retrieve a range of resources in a collection

Retrieve a collection

How to get a collection or resources

Sorting a collection

How to sort a collection of resources

Data

Data format

which data format use

Date and Time

How to deal with date and time data

Internationalization

Providing internationalized data representation (e.g. adapted to the user’s country)

Null data

How to deal with null data

Standards data

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

Error handling

Error format

How to provide information about errors

Errors

How to handle errors

HTTP Methods

DELETE

The DELETE method deletes the specified resource.

Forbidden methods alternatives

What to do when only possible HTTP methods are POST and GET

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.

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.

PATCH

The PATCH method applies partial modifications to a 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.

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

Caching

How to use and provide relevant caching informations

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 Statuses

General information about HTTP statuses usage

HTTP protocol

General informations about HTTP protocol

HTTP Status Redirection

300 Multiple Choices

The 300 (Multiple Choices) status code indicates that the target resource has more than one representation, each with its own more specific identifier, and information about the alternatives is being provided so that the user (or user agent) can select a preferred representation by redirecting its request to one or more of those identifiers. In other words, the server desires that the user agent engage in reactive negotiation to select the most appropriate representation(s) for its needs.

301 Moved Permanently

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

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.

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.

307 Temporary Redirect

The 307 (Temporary Redirect) status code indicates that the target resource resides temporarily under a different URI and the user agent MUST NOT change the request method if it performs an automatic redirection to that URI. Since the redirection can change over time, the client ought to continue using the original effective request URI for future requests.

308 Permanent Redirect

The 308 (Permanent Redirect) status code indicates that the target resource has been assigned a new permanent URI and any future references to this resource ought to use one of the enclosed URIs.

HTTP Status Server Error

500 Internal Server Error

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

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).

503 Service Unavailable

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

HTTP Status Success

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.

201 Created

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

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.

203 Non-Authoritative Information

The 203 (Non-Authoritative Information) status code indicates that the request was successful but the enclosed payload has been modified from that of the origin server’s 200 (OK) response by a transforming proxy.

204 No Content

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

206 Partial Content

The server is delivering only part of the resource (byte serving) due to a range header sent by the client. The range header is used by HTTP clients to enable resuming of interrupted downloads, or split a download into multiple simultaneous streams.

HTTP Status User Error

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).

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.

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.

404 Not Found

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

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.

406 Not Acceptable

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

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.

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.

410 Gone

Indicates that the resource requested is no longer available and will not be available again. This should be used when a resource has been intentionally removed and the resource should be purged. Upon receiving a 410 status code, the client should not request the resource in the future. Clients such as search engines should remove the resource from their indices. Most use cases do not require clients and search engines to purge the resource, and a 404 Not Found may be used instead.

411 Length Required

The request did not specify the length of its content, which is required by the requested resource.

412 Precondition Failed

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

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.

422 Unprocessable Entity

The request was well-formed but was unable to be followed due to semantic errors.

423 Locked

The resource that is being accessed is locked.

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.

429 Too Many Requests

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

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

API chaining

How to chain API call in internal systems

CORS

How to deal with CORS

Debug and diagnose

How to provide informations to debug and diagnose

Developer experience

How to take care of developer experience (DX)

Documentation

How to produce and/or propose API documentation

Guiding inputs

How to help consumers or end user to input relevant data

Performance and bandwidth

How to deal with high traffic or consumers with low bandwith

Query parameters

How to use query parameters

Rate limiting

How to provide information about how many calls a consumer can do

Undo

How to undo things

Naming

Case

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

Language

Which language(s) use when designing an API

Naming

How to name things

Resources

Action resource

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

Batch Bulk

How to handle batch/bulk processing/creation/update/… (e.g. handle multiple resources at conce)

Create resource

How to create resources

Create resource with a specific ID

How to create resource with a provided id

Delete resource

How to delete resources

Dereference Relationships

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

ID with semantic

Using meaningful ids (like me)

Relationships

How to define and use relations between resources

Replace resource

How to replace (or update fully) a resource

Resource

General informations about resources

Resource ID

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

Resource's state

How to change a resource’s state/status (like processed/sent/paid/…)

Retrieve resource

How to retrieve a resource

Retrieve resource partially

How to retrieve partially a resource

Track change

How to track change on resources

URL format

How to design URLs

Update resource

How to update a resource

Update resource partially

How to udate partially a resource

Security

Data privacy

Data privacy concerns

Security

Security concerns