Friday, October 26, 2012

Use Your Own API

One of the early milestones for an engineering team is the development of the first API. Someone wants to use our stuff! Maybe it's another team in the company, or another company altogether. Either way, someone will be consuming your API.

That's truly awesome news. It's always fun to see the great things teams can accomplish with your work.

So how do we create an API? Most of this is fairly straightforward:

  • Figure out what people want to do
  • Create an appropriate security model
  • Settle on an API model (RESTful JSON API? XML-RPC? Choose your technologies.)
  • Define the granularity and the API itself.
  • Document it: training materials, PyDoc/rdoc/javadoc, implementation guide, etc.
The trouble is that most people stop there. There's actually one more step to building a good API:

Use your own API.

All the theory in the world doesn't replace building an application with an API. Things that seem like great ideas on paper turn out to be very painful in the real world - like a too-granular API resulting in hundreds of calls, or hidden workflows enforced by convention only. Things that seemed like they were going to be hard are easy. Data elements show up in unexpected places. This is all stuff you figure out not through examination, but through trying it.

So try it. Create an API, then create a simple app that uses your API. It's amazing what you'll learn.

No comments:

Post a Comment