adidas API design guidelines

adidas

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, …)

Updates and Versioning

How to handle API updates and versioning

Asynchronicity

Asynchronicity

How to handle long operations

Collection Resources

Pagination

How to retrieve a range of resources in a collection

Filtering

How to select some resources in a collection

Data

Data format

which data format use

Internationalization

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

Standards data

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

  • Common Data Types
    data, time, interval, duration, timestamps, language, country code, currency

Date and Time

How to deal with date and time data

Error handling

Errors

How to handle errors

Error format

How to provide information about errors

HTTP Methods

HTTP methods

General information about HTTP methods usage

Forbidden methods alternatives

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

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.

HTTP Protocol

Caching

How to use and provide relevant caching informations

HTTP Statuses

General information about HTTP statuses usage

HTTP Headers

How to use standard or custom HTTP headers

  • Naming Conventions
    Every HTTP Header should use Hyphenated-Pascal-Case. A custom HTTP Header SHOULD NOT start with X- (RFC6648).

HTTP protocol

General informations about 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 Redirection

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.

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.

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.

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.

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

Miscellaneous

Documentation

How to produce and/or propose API documentation

Rate limiting

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

CORS

How to deal with CORS

Naming

Naming

How to name things

Case

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

Resources

Retrieve resource partially

How to retrieve partially a resource

Dereference Relationships

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

Batch Bulk

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

Relationships

How to define and use relations between resources

URL format

How to design URLs

Security

Security

Security concerns