RESTful Thoughts - Planned response status codes for the upcoming RESTful API

Posted By: Nick Floyd

In the interest of honoring standards here is the response status code map for the upcoming Fellowship One RESTful API.  Please comment / ask questions / make suggestions.

Many decisions made for this map came from RFC2616, Fielding’s dissertation, and analysis of several dozen RESTful or REST “like” APIs currently on the programmable web.

200 - ok (GETs, PUTs, and DELETEs)
Entity body - The resource
Example - GET People/1
201 - Resource created (POST)
Response Header - Location will contain the canonical URI
Entity body - the new resource
Example - POST People
301 - Moved Permanently
Response Header - Location will contain the new permanent canonical URI
Entity body - will be empty
Example - GET People/1 has been merged and no longer exists the new URI is People/1
400 - Bad Request: There is an error on the client side.
Response Header - No modification
Entity body - Send back a message on why the request was bad
Example - Malformed XML fails to serialize eon the server
401 - Unauthorized
Response Header - WWW-Authenticate : OAUTH and the challenge or required parameter
Entity body - Optionally, a doc describing the failure
Example - missing OAUTH credentials
403 - Forbidden - Failed authorization
Response Header - No modification
Entity body - explanation of why authorization failed
Example - OAUTH credentials were good, however, the token used for the request was not valid or user associated with the token does not have rights to the resource
404 - Not Found: When a client requests a URI that does not map to a resource on the server
Response Header - No modification
Entity body - will be empty
Example - GET People/1 does not exist, optionally a 410 may be used (see below)
405 - Method not allowed
Response Header - Allow: GET, POST - list the HTTP methods the resource supports
Entity body - will be empty
Example - POST People/1/Status <- an attempt to create a status when only GET is available
409 - Conflict: Client tried to put the servers resource in an impossible or inconsistent state
Response Header - Allow: GET, POST - list the HTTP methods the resource supports
Entity body - will be empty
Example - POST People/1/Status <- an attempt to create a status when only GET is available
410 - Gone: server knew there used to be a resource but it’s gone now
Response Header - No modification
Entity body - explanation of conflicts
Example - PUT People/1 modifying “Weblink” credentials for People/1 that are already used by People/2
415 - Unsupported Media Type
Response Header - Code detailed supported media types for the given resource
Entity body - will be empty
Example - Resource only supports XML and JSON, but the client sends application/atom+xml
500 - Internal Server Error
Response Header - No modification
Entity body - will be empty
Example - The server encountered an unexpected condition which prevented it from fulfilling the request.
This response status code map is subject to change, however, in the current build of the API these rules exist as defined above.

Posted In: API, News,

Comments:
No one has commented yet. Be the first!
Commenting is not available in this channel entry.

Categories:

Previous Posts:


Subscribe to the RSS feed!