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

geemus · geemus · commit fba98f08b50a · 2015-05-13T18:56:47.000-05:00
Move bullets from Requests to Responses
diff --git 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
