What I've learned from reading RESTful Web APIs

I've recently finished reading the book RESTful Web APIs by Leonard Richardson, Mike Amundsen, Sam Ruby.

Wish I've read this book before building an API. To summarize the things I would have done different (and you've should have done probably too):

• Use standard naming conventions for properties from for example: http://schema.org/docs/schemas.html
• Don't use application/json but a custom format like application/vnd.sameproblemmorecode.blog+json
• Make better use of the default HTTP Headers (e.g. the WWW-Authenticate and Link header)
• Return errors as described in https://tools.ietf.org/html/draft-nottingham-http-problem-06
• Create hypermedia links in the HTTP headers to describe possible links. These links should also have standartized names from for example http://www.iana.org/assignments/link-relations/link-relations.xhtml
• If time allows; event create hypermedia profiles (this allows the server to change without breaking clients). One of the writers is also writing a book on how to create hypermedia driven clients for this.
• Make sure to reuse as much standards as possible, we don't need another new standard. This enables us to reuse webcomponents (or at least parts of) between projects.

Hope this helps.

Cheers,

Luuk