I like this best practices guide to designing APIs by Vinay Sahni.

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:

• Advanced REST Client
• Postman REST Client

Remember:

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:

• API Best Practises Blog over at Apigee
• Designing REST + JSON APIs at Stormpath
• The Stripe API Docs
• The GitHub API Docs