For the Firefox Marketplace we are building out a REST API. We have had one for a while for app submission and it is now growing to provide an API for fireplace, an app that will go onto Firefox OS phones.
When writing a REST API you have an opportunity to be more expressive than just returning web pages and a few normal statuses like 200, 302, 403 and 500. A HTTP status can tell the client quickly and succinctly what happened. Most client libraries assume that a status with a range either means a success or failure. So returning a status code 202 over 200, will work in pretty much every library and convey more information.
Some of the HTTP status codes we are using:
- 201 Created: we have created the new resource (e.g.: app).
- 202 Accepted: we haven't processed yet, but we will do. Normally this means we've pushed the request off to a Celery queue.
- 402 Payment Required: you tried to install an app without paying for it.
- 409 Conflict: this would generate a conflict in the state of the resource. For example you tried to POST something instead of a PUT or PATCH.
- 429 Too Many Requests: you've made too many requests and we've throttled you.
- 451 Unavailable for Legal Reasons: the app is unavailable for legal reasons, perhaps due to region or content restrictions.
Unfortunately some of these status codes are a little less well defined. For code 451 there are currently at least 3 proposed meanings: something about users mailboxes and something RTSP along with the legal restriction. But hopefully users of our API will realise we aren't using Exchange or RTSP and maybe even read the docs to find out what this means.
Using HTTP statuses is simple and descriptive. I like that.