7 Rules of Thumb When You Build an API

Consuming 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

Be sure to read the next Best Practices article: Pros and Cons of Outsourcing Your Apps to APIs


Comments (5)


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

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.

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.

[...] 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 [...]

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