#mark nottingham

[mirrorontheworld]

HTTP/2 is getting close to being real, with lots of discussions and more implementations popping up every week. What does a new version of the Web’s protocol mean for you? Here are some early answers.

[dragoni]

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"] }