Public API design - handling failure with a http code? Is that REST?

Question

I am just about to make a webservice available for fellow programmers in my sector using PHP on my own server.

As this is the first time I have done this, I first investigated APIs that I frequently use, Flickr etc.

My service returns granular data extracted from a very large csv file by examining GET arguments, it is read-only.

The data is returned in a variety of formats, xml, json, jsonp etc.

example of the call: /?offices=ABC|XYZ&format=xml

Firstly, I'd like to know if I am I correct in terming my service an "API"?

Also I would also like to know how best to handle failure.

I return straight text messages in the case of a user not submitting the expected input - "you failed to submit any offices".

In the case of any other unforeseen malfunction, at the moment it returns a failure message in payload of the chosen format, eg json with the single array "fail" in it and I have documented this.

Having read up a little on REST recently, when a failure is not caused by misuse of the "API" - should I return something other than HTTP code 200?

If you were accessing this service, what would you prefer to see?

Should I make this another GET option?

e.g /?offices=ABC|XYZ&format=xml&on_failure=http

Or am I getting muddled between the terms API and REST?

SO suggested this post, which deals with 400/401

http://stackoverflow.com/questions/1959947/whats-an-appropriate-http-status-code-to-return-by-a-rest-api-service-for-a-vali

but I am looking for clarification about the terms I am using. If the payload contains the error message - as in the case of Flickr then why should I wander away from that?

Answer 1

The larger providers like Flickr and Twitter have muddied the definition of REST quite a bit. Many developers now mistakenly believe that any service or API over HTTP is "RESTful." What you describe here is more of a data Web service using a form of RPC. Truly RESTful APIs use fluent HTTP and Web standards, and are resource centric.

To answer the main question about HTTP status codes, I would say that for RPC services it's not necessary, as the HTTP status codes won't always directly translate to method call errors. A better approach would be to map your own error codes and return them along with the status message.

For example, an RPC service for user lookups may return the following on success:

SUCCESS=1
USERNAME=example
FIRSTNAME=Example
LASTNAME=User
DISPLAYNAME=Example User

The same service may return the following on failure:

SUCCESS=0
ERRORCODE=1002
ERRORMSG=User subsystem error; requested user was not found.

In an RPC service, the exact details of the response are very flexible. All it does is relay the results of the method call to the invoker. As long as you document what the developer should see, and return clear and consistent messages, it'll work out just fine. The only HTTP status codes an RPC service should return are 200 and 500 (and only then when things break so badly you can't even return a proper error).

Back to the matter of REST, the same user service can be made RESTful if we think of a user as a resource and use an appropriate URL scheme. The very, very basic makeup of a RESTful API are as follows:

GET /api/users - should return a list of available user accounts in the system.

GET /api/users/example - should return details of the example account; returns a 404 HTTP status if the user does not exist.

POST /api/users - create a new user account; should return a link to the newly created account (ways of doing this vary, but the LOCATION header makes sense here). Various HTTP status codes may be returned depending on the result.

PUT /api/users/example - edit the details of an existing user account. Various HTTP status codes may be returned depending on the result.

DELETE /api/users/example - delete an existing user account. Various HTTP status codes may be returned depending on the result.

The standard HTTP status codes most common to RESTful interfaces are below.

• 200 OK - The request was successfully completed. If this request created a new resource that is addressable with a URI, and a response body is returned containing a representation of the new resource, a 200 status will be returned with a Location header containing the canonical URI for the newly created resource.
• 201 Created - A request that created a new resource was completed, and no response body containing a representation of the new resource is being returned. A Location header containing the canonical URI for the newly created resource should also be returned.
• 202 Accepted - The request has been accepted for processing, but the processing has not been completed. Per the HTTP/1.1 specification, the returned entity (if any) SHOULD include an indication of the request's current status, and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled.
• 204 No Content - The server fulfilled the request, but does not need to return a response message body.
• 400 Bad Request - The request could not be processed because it contains missing or invalid information (such as validation error on an input field, a missing required value, and so on).
• 401 Unauthorized - The authentication credentials included with this request are missing or invalid.
• 403 Forbidden - The server recognized your credentials, but you do not possess authorization to perform this request.
• 404 Not Found - The request specified a URI of a resource that does not exist.
• 405 Method Not Allowed - The HTTP verb specified in the request (DELETE, GET, HEAD, POST, PUT) is not supported for this request URI.
• 406 Not Acceptable - The resource identified by this request is not capable of generating a representation corresponding to one of the media types in the Accept header of the request.
• 409 Conflict - A creation or update request could not be completed, because it would cause a conflict in the current state of the resources supported by the server (for example, an attempt to create a new resource with a unique identifier already assigned to some existing resource).
• 500 Internal Server Error - The server encountered an unexpected condition which prevented it from fulfilling the request.
• 501 Not Implemented - The server does not (currently) support the functionality required to fulfill the request.
• 503 Service Unavailable - The server is currently unable to handle the request due to temporary overloading or maintenance of the server.

Hopefully this information is useful, and not overload. :-)