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
What's an appropriate HTTP status code to return by a REST API service for a validation failure?
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?
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.
Hopefully this information is useful, and not overload. :-)