A common part of HTTP-based APIs is telling the client that something has gone wrong. Most APIs do this in some fashion, whether they call it a “Fault” (very SOAP-y), “Error” or whatever. Most of them define a new format...
Current norm, i.e. Amazon’s,OpenStack’s, Twitter’s, Facebook’s, and SalesForce’s
{"errors":[{"message":"Sorry, that page does not exist","code":34}]}
Proposed:
Good HTTP APIs don’t make developers hunt through documentation to find things like this; self-documenting formats give is a way to communicate these kinds of details in a way that’s easy to find.
Good HTTP APIs also use media types to indicate the format of the content, for similar reasons; however, most of these don’t, and as a result developers and tools again need to understand that they’re working with a particular API, rather than just examining the message.
...
HTTP/1.1 403 Forbidden Content-Type: application/api-problem+json Content-Language: en { "problemType": "http://example.com/probs/out-of-credit", "title": "You do not have enough credit.", "detail": "Your current balance is 30, but that costs 50.", "problemInstance": "http://example.net/account/12345/msgs/abc", "balance": 30, "accounts": ["http://example.net/account/12345", "http://example.net/account/67890"] }