Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/hyperoslo/api-playbook

A place to define the conventions we use to build APIs
https://github.com/hyperoslo/api-playbook

Last synced: 4 months ago
JSON representation

A place to define the conventions we use to build APIs

Awesome Lists containing this project

README 

          
# API styleguide



A place to define the conventions we use to build APIs



- [API styleguide](#api-styleguide)

	- [Basic Tools](#basic-tools)

	- [Localization](#localization)

	- [Heroku conventions](#heroku-conventions)

		- [Foundations](#foundations)

			- [Separate Concerns](#separate-concerns)

			- [Require Secure Connections](#require-secure-connections)

			- [Support ETags for Caching](#support-etags-for-caching)

		- [Requests](#requests)

			- [Accept serialized JSON in request bodies](#accept-serialized-json-in-request-bodies)

			- [Use consistent path formats](#use-consistent-path-formats)

				- [Resource names](#resource-names)

			- [Minimize path nesting](#minimize-path-nesting)

		- [Responses](#responses)

			- [Return appropriate status codes](#return-appropriate-status-codes)

			- [Provide full resources where available](#provide-full-resources-where-available)

			- [Provide standard timestamps](#provide-standard-timestamps)

			- [Use UTC times formatted in ISO8601](#use-utc-times-formatted-in-iso8601)

			- [Nest foreign key relations](#nest-foreign-key-relations)

			- [Generate structured errors](#generate-structured-errors)

			- [Show rate limit status](#show-rate-limit-status)

			- [Keep JSON minified in all responses](#keep-json-minified-in-all-responses)



## Basic Tools



It's quite common in Hyper to build APIs with [Ruby on Rails](http://rubyonrails.org/), so most of these

conventions are designed to work well with Rails.



## Localization



When the responses need to be localized, it's recommended for the client to send

the [`Accept-Language`](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.4)

header:



```

Accept-Language: nb-no, no, en

```



## Heroku conventions



We take in account most of [Heroku's conventions for building APIs][6ea5c025].



  [6ea5c025]: https://github.com/interagent/http-api-design "Heroku's conventions for building APIs"



### Foundations



#### Separate Concerns



Keep things simple while designing by separating the concerns between the

different parts of the request and response cycle. Keeping simple rules here

allows for greater focus on larger and harder problems.



Requests and responses will be made to address a particular resource or

collection. Use the path to indicate identity, the body to transfer the

contents and headers to communicate metadata. Query params may be used as a

means to pass header information also in edge cases, but headers are preferred

as they are more flexible and can convey more diverse information.



#### Require Secure Connections



Require secure connections with TLS to access the API, without exception.

It’s not worth trying to figure out or explain when it is OK to use TLS

and when it’s not. Just require TLS for everything.



Ideally, simply reject any non-TLS requests by not responding to requests for

http or port 80 to avoid any insecure data exchange. In environments where this

is not possible, respond with `403 Forbidden`.



Redirects are discouraged since they allow sloppy/bad client behaviour without

providing any clear gain.  Clients that rely on redirects double up on

server traffic and render TLS useless since sensitive data will already

 have been exposed during the first call.



#### Support ETags for Caching



Include an `ETag` header in all responses, identifying the specific

version of the returned resource. This allows users to cache resources

and use requests with this value in the `If-None-Match` header to determine

if the cache should be updated.



### Requests



#### Accept serialized JSON in request bodies



Accept serialized JSON on `PUT`/`PATCH`/`POST` request bodies, either

instead of or in addition to form-encoded data. This creates symmetry

with JSON-serialized response bodies, e.g.:



```bash

$ curl -X POST https://service.com/apps \

    -H "Content-Type: application/json" \

    -d '{"name": "demoapp"}'



{

  "id": "01234567-89ab-cdef-0123-456789abcdef",

  "name": "demoapp",

  "owner": {

    "email": "username@example.com",

    "id": "01234567-89ab-cdef-0123-456789abcdef"

  },

  ...

}

```



#### Use consistent path formats



##### Resource names



Use the plural version of a resource name unless the resource in question is a

singleton within the system (for example, in most systems a given user would

only ever have one account). This keeps it consistent in the way you refer to

particular resources.



#### Minimize path nesting



In data models with nested parent/child resource relationships, paths

may become deeply nested, e.g.:



```

/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}

```



Limit nesting depth by preferring to locate resources at the root

path. Use nesting to indicate scoped collections. For example, for the

case above where a dyno belongs to an app belongs to an org:



```

/orgs/{org_id}

/orgs/{org_id}/apps

/apps/{app_id}

/apps/{app_id}/dynos

/dynos/{dyno_id}

```



### Responses



#### Return appropriate status codes



Return appropriate HTTP status codes with each response. Successful

responses should be coded according to this guide:



* `200`: Request succeeded for a `GET` call, for a `DELETE` or

  `PATCH` call that completed synchronously, or for a `PUT` call that

  synchronously updated an existing resource

* `201`: Request succeeded for a `POST` call that completed

  synchronously, or for a `PUT` call that synchronously created a new

  resource

* `202`: Request accepted for a `POST`, `PUT`, `DELETE`, or `PATCH` call that

  will be processed asynchronously

* `206`: Request succeeded on `GET`, but only a partial response

  returned: see [above on ranges](#divide-large-responses-across-requests-with-ranges)



Pay attention to the use of authentication and authorization error codes:



* `401 Unauthorized`: Request failed because user is not authenticated

* `403 Forbidden`: Request failed because user does not have authorization to

  access a specific resource



Return suitable codes to provide additional information when there are errors:



* `422 Unprocessable Entity`: Your request was understood, but contained invalid parameters

* `429 Too Many Requests`: You have been rate-limited, retry later

* `500 Internal Server Error`: Something went wrong on the server, check status

  site and/or report the issue



Refer to the [HTTP response code spec](https://tools.ietf.org/html/rfc7231#section-6)

for guidance on status codes for user error and server error cases.



#### Provide full resources where available



Provide the full resource representation (i.e. the object with all

attributes) whenever possible in the response. Always provide the full

resource on 200 and 201 responses, including `PUT`/`PATCH` and `DELETE`

requests, e.g.:



```bash

$ curl -X DELETE \  

  https://service.com/apps/1f9b/domains/0fd4



HTTP/1.1 200 OK

Content-Type: application/json;charset=utf-8

...

{

  "created_at": "2012-01-01T12:00:00Z",

  "hostname": "subdomain.example.com",

  "id": "01234567-89ab-cdef-0123-456789abcdef",

  "updated_at": "2012-01-01T12:00:00Z"

}

```



202 responses will not include the full resource representation,

e.g.:



```bash

$ curl -X DELETE \  

  https://service.com/apps/1f9b/dynos/05bd



HTTP/1.1 202 Accepted

Content-Type: application/json;charset=utf-8

...

{}

```



#### Provide standard timestamps



Provide `created_at` and `updated_at` timestamps for resources by default,

e.g:



```javascript

{

  // ...

  "created_at": "2012-01-01T12:00:00Z",

  "updated_at": "2012-01-01T13:00:00Z",

  // ...

}

```



These timestamps may not make sense for some resources, in which case

they can be omitted.



#### Use UTC times formatted in ISO8601



Accept and return times in UTC only. Render times in ISO8601 format,

e.g.:



```

"finished_at": "2012-01-01T12:00:00Z"

```



#### Nest foreign key relations



Serialize foreign key references with a nested object, e.g.:



```javascript

{

  "name": "service-production",

  "owner": {

    "id": "5d8201b0..."

  },

  // ...

}

```



Instead of e.g.:



```javascript

{

  "name": "service-production",

  "owner_id": "5d8201b0...",

  // ...

}

```



This approach makes it possible to inline more information about the

related resource without having to change the structure of the response

or introduce more top-level response fields, e.g.:



```javascript

{

  "name": "service-production",

  "owner": {

    "id": "5d8201b0...",

    "name": "Alice",

    "email": "alice@heroku.com"

  },

  // ...

}

```



#### Generate structured errors



Generate consistent, structured response bodies on errors. Include a

machine-readable error `id`, a human-readable error `message`, and

optionally a `url` pointing the client to further information about the

error and how to resolve it, e.g.:



```

HTTP/1.1 429 Too Many Requests

```



```json

{

  "id":      "rate_limit",

  "message": "Account reached its API rate limit.",

  "url":     "https://docs.service.com/rate-limits"

}

```



Document your error format and the possible error `id`s that clients may

encounter.



#### Show rate limit status



Rate limit requests from clients to protect the health of the service

and maintain high service quality for other clients. You can use a

[token bucket algorithm](http://en.wikipedia.org/wiki/Token_bucket) to

quantify request limits.



Return the remaining number of request tokens with each request in the

`RateLimit-Remaining` response header.



#### Keep JSON minified in all responses



Extra whitespace adds needless response size to requests, and many

clients for human consumption will automatically "prettify" JSON

output. It is best to keep JSON responses minified e.g.:



```json

{"beta":false,"email":"alice@heroku.com","id":"01234567-89ab-cdef-0123-456789abcdef","last_login":"2012-01-01T12:00:00Z","created_at":"2012-01-01T12:00:00Z","updated_at":"2012-01-01T12:00:00Z"}

```



Instead of e.g.:



```json

{

  "beta": false,

  "email": "alice@heroku.com",

  "id": "01234567-89ab-cdef-0123-456789abcdef",

  "last_login": "2012-01-01T12:00:00Z",

  "created_at": "2012-01-01T12:00:00Z",

  "updated_at": "2012-01-01T12:00:00Z"

}

```