7 Rules of Thumb When You Build an API

Simon Hamp, October 11th, 2010

GnipConsuming APIs is something most developers–and even some non-developers–are doing most of the time. It’s becoming more common to build an API, in addition to using them. For all of those of you who are just getting your feet wet with this process, data portability service Gnip has shared a few pointers to keep you on the straight and narrow.

  • Use Standard HTTP Response Codes
  • Publish Your Rate Limits
  • Use Friendly Ids, Not System Ids
  • Allow Us to Limit Response Data
  • Keep Your Docs Up to Date
  • Publish Your Search Parameter Constraints
  • Use Your Mailing List

One rule of thumb that stands out is to use standard response codes. It’s so easy to forget that sometimes there’s a HTTP response code that could be used in place of an in-content message. This can save bandwidth and is more standards-compliant, and therefore more predictable to code against.

And there’s a really important note too about keeping documentation up to date. It’s so important that it’s a matter of life and death (of your API). So, try to stay on top of the docs and read our Web API Documentation Best Practices.

You’ll be able to build a much happier community around your tools if you provide them with a clear set of instructions and an open channel of positive communication. This will definitely get you the thumbs-up from other developers. And don’t forget: a happy community is a vocal one!

Be sure to read Gnip’s entire list, which includes additional information about each guideline.

Photo by joeltelling

Both comments and pings are currently closed.

5 Responses to “7 Rules of Thumb When You Build an API”

October 11th, 2010
at 12:26 am
Comment by: Kent Brewster

Using standard HTTP response codes seems like a fine idea until you start serving up JSON wrapped in a callback for inclusion as dynamically-generated SCRIPT tags. If the HTTP response code isn’t 200, your Web app won’t ever see the API output.

October 11th, 2010
at 6:15 am
Comment by: Mike

@Kent – You could handle that by detecting those browser requests and altering the response code for them only.

February 11th, 2012
at 2:27 am
Comment by: Sebastian Spier

Some additional comments:

1) Look at a lot of APIs before building your own. Try them out. Learn from the good and bad decisions that others have made before you.

2) If you can, provide an API console for developers, so that the initial hurdle to getting started is really really low!

3) Include the properly interpreted request parameters in the response. This makes it much easier for the developers to debug their API calls. (most APIs solve this by including a request and response section)

4) Extra tip from an YQL fan: Try to create a YQL table for your API. If that turns out to be difficult, then you have probably designed a very non-standard API.

April 1st, 2012
at 11:41 pm
Comment by: Yiddish

API is a set of routines, protocols, and tools for building software applications.

May 13th, 2012
at 6:07 pm
Comment by: A Documentation Model for a RESTful API | mobiarch

[...] can be left guessing about exactly how to invoke a service. There is a reason good documentation is considered a key best practice in a RESTful API [...]

Follow the PW team on Twitter

APIs, mashups and code. Because the world's your programmable oyster.

John Musser
Founder, ProgrammableWeb

Adam DuVander
Executive Editor, ProgrammableWeb. Author, Map Scripting 101. Lover, APIs.