Can I explore your API in a browser address bar?

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:

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:

About brendansterne

Director of Innovation Labs, Indeed.com
This entry was posted in Uncategorized and tagged , , . Bookmark the permalink.

One Response to Can I explore your API in a browser address bar?

  1. Peter Grape says:

    I also recommend the Swagger tool to auto generate a REST API GUI on the fly.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s