From a7a1c6baf451ec99846585f35533419e3bd15e4a Mon Sep 17 00:00:00 2001 From: Michael Stowe Date: Mon, 5 Sep 2016 10:10:21 -0700 Subject: [PATCH 1/2] Updated HTTP Status Codes Replaced recommendation to use three ambiguous status codes with actual standard status codes as ambiguous status codes or categories can be obtained via the first # in the status code sequence (ie 2xx, 3xx, 4xx, 5xx) and prevents the client from understanding what action is actually taking place (was an item updated or created with a PUT, has the delete been performed, is the item missing or has it been removed, is it a malformed request or do I not have permission to do it, etc). --- README.md | 31 +++++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 38a1b0d..4495ee6 100644 --- a/README.md +++ b/README.md @@ -126,10 +126,33 @@ Error responses should include a common HTTP status code, message for the develo http://drupal.org/node/444444", } -Use three simple, common response codes indicating (1) success, (2) failure due to client-side problem, (3) failure due to server-side problem: -* 200 - OK -* 400 - Bad Request -* 500 - Internal Server Error +It is recommended to use a standard Descriptive Error Format such as [JSON API's error format](http://jsonapi.org/format/#errors), [error.vnd](https://github.com/blongden/vnd.error), or Google Errors. + +###HTTP Status Codes + +Use [standard HTTP Status Codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) to return the status of the API call, ranging from successful, to redirects, to client/ server errors. This provides critical information to the client including the category of error (the first # of the response) as well as the exact action that was taken. This information becomes extremely important in telling the client what to expect, or what actions are needed on the clients end. + +Some of the more popular, standard HTTP Status Codes are: + +| STATUS CODE | USE WHEN | +| ----------- | ---------- | +| **2XX** | **SUCCESSFUL** | +| 200 | Ok, or Updated (but not created) | +| 201 | Created - this is important to inform the client of an object creation, especially when such action may not be anticipated by the user (ie using a PUT) | +| 202 | Accepted - but the action has not yet been completed. For example, batch transactions, deletes, or items that require additional processing time by the server | +| 204 | No content returned (common with a delete) | +| **3XX** | **REDIRECTION/ NOT MODIFIED** | +| 301 | Resource moved permanently and urls should be updated | +| 304 | The resource has not been modified since the last version requested - as such there is no need to call the resource again | +| 303/ 307 | The resource has been moved temporarily | +| **4XX** | **CLIENT ERROR** | +| 400 | Bad request (malformed) made by client | +| 401 | Unauthorized - client authentication for this resource has failed | +| 403 | Forbidden - authorized client does not have permissions to do this | +| 404 | Resource cannot be found, did not previously exist (status code 410), and may be available in the future | +| 405 | HTTP Method requested is not allowed (ie trying to call a DELETE on a COLLECTION) | +| 415 | Content-Type/ Media-Type not allowed (trying to access XML when only JSON is supported) | +| 429 | The client has made too many requests | ## Versions From 32557f5202541b32f7da6bf7f24a7bb237ae7fc4 Mon Sep 17 00:00:00 2001 From: Michael Stowe Date: Mon, 5 Sep 2016 10:25:43 -0700 Subject: [PATCH 2/2] Adding back in 500 errors Knew I forgot something :-p - Added the 5XX back into the status codes - universal for "we have no idea what actually happened." --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 4495ee6..5c3da09 100644 --- a/README.md +++ b/README.md @@ -153,6 +153,8 @@ Some of the more popular, standard HTTP Status Codes are: | 405 | HTTP Method requested is not allowed (ie trying to call a DELETE on a COLLECTION) | | 415 | Content-Type/ Media-Type not allowed (trying to access XML when only JSON is supported) | | 429 | The client has made too many requests | +| **5XX** | **SERVER ERROR** | +| 500 | An error occurred on the server side and the request could not be successfully processed | ## Versions