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

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

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

$ 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.:

$ curl -X DELETE \

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

HTTP/1.1 202 Accepted

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

...

{}