In it he offers some excellent advice, but one particular design principle is worth heeding and has lots of implications, namely the API should be “explorable via a browser address bar.” This means several things (some of which he mentions, some of which he doesn’t):
- Major versioning in the url (api.xx.com/v1/)
- Use SSL/HTTPS with apikey params (or basic auth)
- Nicely formatted JSON output
- Content-Type overriding via resource extension to the url (/users.json)
- Pagination in query params (offset & length)
- Overriding HTTP methods (…&_method=DELETE to delete from browser)
Vinay does make some recommendations that preclude exploring the API in a browser, e.g. use JSON as the body content when creating resources with a POST. But there aren’t alternatives for POSTing content from a browser anyway, and using GET to create resources is bad bad bad.
If you do want to stay in the browser when POSTing to an API, then there are two great Chrome extensions you should check out:
An API is a user interface for developers. Put the effort in to ensure it’s not just functional but pleasant to use.
There are some other great resources for API design considerations. I recommend checking out: