diff --git a/README.md b/README.md index 7a3a1f9..45a36ba 100644 --- a/README.md +++ b/README.md @@ -29,14 +29,14 @@ We welcome [contributions](CONTRIBUTING.md) to this guide. * [Provide Request-Ids for Introspection](#provide-request-ids-for-introspection) * [Divide Large Responses Across Requests with Ranges](#divide-large-responses-across-requests-with-ranges) * [Requests](#requests) - * [Return appropriate status codes](#return-appropriate-status-codes) - * [Provide full resources where available](#provide-full-resources-where-available) * [Accept serialized JSON in request bodies](#accept-serialized-json-in-request-bodies) * [Use consistent path formats](#use-consistent-path-formats) * [Downcase paths and attributes](#downcase-paths-and-attributes) * [Support non-id dereferencing for convenience](#support-non-id-dereferencing-for-convenience) * [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 resource (UU)IDs](#provide-resource-uuids) * [Provide standard timestamps](#provide-standard-timestamps) * [Use UTC times formatted in ISO8601](#use-utc-times-formatted-in-iso8601) @@ -120,71 +120,6 @@ ordering, and iteration. ### Requests -#### 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 -... -{} -``` - #### Accept serialized JSON in request bodies Accept serialized JSON on `PUT`/`PATCH`/`POST` request bodies, either @@ -284,6 +219,71 @@ case above where a dyno belongs to an app belongs to an org: ### 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 resource (UU)IDs Give each resource an `id` attribute by default. Use UUIDs unless you