Permalink
Browse files

Merge pull request #76 from ms-ati/patch-2

Move bullets from Requests to Responses
  • Loading branch information...
geemus committed May 13, 2015
2 parents 4391418 + 53c5425 commit fba98f08b50acbb08b7b30c012a6d0ca795e29ee
Showing with 67 additions and 67 deletions.
  1. +67 −67 README.md
View
134 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

0 comments on commit fba98f0

Please sign in to comment.