REST API Guidelines 📜

This is a shortened merge of Google’s API design guide and Microsoft REST API Guidelines .

To write OpenAPI schema swagger documentation is useful. To quickly iterate on a design, semantic versioning should be used. To generate human-readable diff of different versions openapi-diff can be useful.

1. Resource-oriented design

In general URL paths should follow this scheme:

A storage service has a collection of buckets, where each bucket has a collection of objects.

Another example:

https://api.contoso.com/v1.0/people/7011042402/inbox

Resource names should be noun and not verb. Resource names should be plural.

2. Naming and standards

Microsoft mostly uses camelCase, Google mostly uses snake_case - this guide will be using camelCase.

• Acronyms should follow the casing conventions as though they were regular words (e.g. Url).
• All identifiers including namespaces, entityTypes, entitySets, properties, actions, functions and enumeration values should use lowerCamelCase.
• HTTP headers are the exception and should use standard HTTP convention of Capitalized-Hyphenated-Terms.
• Full words should be preferred (e.g. message instead of msg).

Common property names should be used where applicable:

For resource fields that cannot be set by the clients, they must be documented as “Output only” fields.

Canonical identifier

In addition to friendly URLs, resources that can be moved or be renamed SHOULD expose a URL that contains a unique stable identifier. It MAY be necessary to interact with the service to obtain a stable URL from the friendly name for the resource, as in the case of the /my shortcut used by some services.

One option is to use ULID .

Time

All time values are should be represented as RFC 3339 timestamps:

2019-10-12T07:20:50.52Z      (UTC+0)
2019-10-12T07:20:50.52+00:00 (UTC+0)
2019-10-12T14:20:50.52+07:00 (UTC+7)
2019-10-12T03:20:50.52-04:00 (UTC-4)

Durations

Durations need to be serialized in conformance with ISO 8601 with the following format:

P[n]Y[n]M[n]DT[n]H[n]M[n]S

Example (3 years, 6 months, 4 days, 12 hours, 30 minutes, and 5 seconds):

P3Y6M4DT12H30M5S

Intervals

Intervals are defined as part of ISO 8601. It seems sufficient to support only the following formats:

• Start and end, such as

  2007-03-01T13:00:00Z/2008-05-11T15:30:00Z
  

• Start and duration, such as

  2007-03-01T13:00:00Z/P1Y2M10DT2H30M
  

3. HTTP Methods

4. Headers

A good reference for standard headers can be found on MDN . The most common are listed below.

Standard request headers

Standard response headers

5. Status codes

Full list of HTTP status codes can be found on MDN . The most common are listed below.

6. JSON body

Success

To separate actual data from metadata (lake pagination, etc), the JSON body of response should put data object under value key.

{
  "value": [
    { "street": "1st Avenue", "city": "Seattle" },
    { "street": "124th Ave NE", "city": "Redmond" }
  ]
}

Error

Error object should be under error key. Response body should use the following structure:

{
  "error": {
    "code": "BadArgument",
    "message": "Multiple errors in ContactInfo data",
    "target": "ContactInfo",
    "details": [
      {
        "code": "NullValue",
        "target": "PhoneNumber",
        "message": "Phone number must not be null"
      },
      {
        "code": "NullValue",
        "target": "LastName",
        "message": "Last name must not be null"
      },
      {
        "code": "MalformedValue",
        "target": "Address",
        "message": "Address is not valid"
      }
    ]
  }
}

code, message and details (can be empty array) are required fields.

Note, that message fields are not to be used to display to client. Instead client and server should design a set of error codes specified by code field (that does not nececcerily match HTTP status codes).

7. Common patterns

Pagination

All APIs that return lists should support pagination. Client-driven paging seems to be the most popular.

Clients MAY use $top and $skip query parameters to specify a number of results to return and an offset into the collection. When both $top and $skip are given by a client, the server SHOULD first apply $skip and then $top on the collection.

GET http://api.contoso.com/v1.0/people?$top=5&$skip=2

For server-driven paging, Google’s guide is useful.

Sorting

Sorting is defined by a query parameter $orderBy.

The string value should follow SQL syntax: comma separated list of fields. For example: foo,bar. The default sorting order is ascending. To specify descending order for a field, a suffix desc should be appended to the field name. For example: foo desc,bar.

Filtering

$filter query parameter is evaluated for each resource in the collection, and only items where the expression evaluates to true are included in the response.

Example 1: return all Products whose Price is less than $10.00:

GET https://api.contoso.com/v1.0/products?$filter=price lt 10.00

Example 2: all products with the name ‘Milk’ that also have a price less than 2.55:

GET https://api.contoso.com/v1.0/products?$filter=name eq 'Milk' and price lt 2.55

The value of the $filter option is a Boolean expression.

Microsoft lists the set of operations filter should support:

For more examples and operator precedence look at Microsoft’s guide .

When a filter is performed on a collection and the result set is empty you must respond with a valid response body and a 200 response code.

Long Running Operations

Services should be as responsive as possible, so as not to block callers. As a rule of thumb any API call that is expected to take longer than 0.5 seconds in the 99th percentile, should consider using the following Long-running Operations pattern for those calls.

The operation resource must be returned directly as the response message and any immediate consequence of the operation should be reflected in the API. For example, when creating a resource, that resource should appear in GET method though the resource should indicate that it is not ready for use. When the operation is complete, the value field should contain the value that would have been returned directly, if the method was not long running.

Access Sub-Collections

Sometimes, an API needs to let a client search across sub- collections. For example, the Library API has a collection of shelves, and each shelf has a collection of books, and a client wants to search for a book across all shelves.

GET https://library.googleapis.com/v1/shelves/-/books?filter=xxx
GET https://library.googleapis.com/v1/shelves/-/books/{id}

ETags

In typical usage, when a URL is retrieved, the Web server will return the resource’s current representation along with its corresponding ETag value, which is placed in an HTTP response header “ETag” field:

ETag: "686897696a7c876b7e"

The client may then decide to cache the representation, along with its ETag. Later, if the client wants to retrieve the same URL resource again, it will first determine whether the locally cached version of the URL has expired (through the Cache-Control and the Expire headers). If the URL has not expired, it will retrieve the locally cached resource. If it is determined that the URL has expired (is stale), the client will send a request to the server that includes its previously saved copy of the ETag in the “If-None-Match” field.

If-None-Match: "686897696a7c876b7e"

On this subsequent request, the server may now compare the client’s ETag with the ETag for the current version of the resource. If the ETag values match, meaning that the resource has not changed, the server may send back a very short response with a HTTP 304 Not Modified status. The 304 status tells the client that its cached version is still good and that it should use that.

Throttling

Services should be as responsive as possible, so as not to block callers. As a rule of thumb any API call that is expected to take longer than 0.5 seconds in the 99th percentile, should consider using the Long-running Operations pattern for those calls.

HTTP specifies two return codes for these scenarios: ‘429 Too Many Requests’ and ‘503 Service Unavailable’. Services should use 429 for cases where clients are making too many calls and can fix the situation by changing their call pattern. Services should respond with 503 in cases where general load or other problems outside the control of the individual callers is responsible for the service becoming slow.

To avoid cascading failures, Circuit Breaker pattern can be used (Go implementation ).

Notes

• [1] The time format in Date header is important .