So you want to offer a public API ...

API, by thesmith You are awesome.

Your startup just came up with a cool new piece of tech. Others might want to use it as well. The best way to do that is offering it up as a service - a RESTful API even.

Hey, it made Twitter famous. Surely it will help you gain some traction as well ... Might even make you some money! Now we're talking!

So ... what goes into making an API?

You just take the same interface your over-architected architecture uses internally, open it up, announce it on HackerNews and Twitter and Reddit and away we go. Right? Right.

Not right.

To offer a public API you need:

  • some way to authorize developers
  • throttling control so you don't get swarmed
  • deciding whether you're going to charge money or not
  • usually when charging, more requests means more money -> you need a way of enforcing quotas
  • good tools to see what's happening with the service
  • good documentation
  • support
  • support
  • support

Did I mention you are going to have to offer support?

Effort :(

Oh and don't forget permissions, maybe you want to give different people access to different endpoints of the API. Maybe some parts of the API have different usage quotas than others, or perhaps the throttling behaves differently depending on how many resources it takes to service different requests.

Suddenly, this is much more than you bargained for - all you wanted is to simply throw an API out there, see if it sticks and maybe collect some side income for your startup.

I know, I've been there.

A few years ago I offered an API without making sure I'm doing it properly - it's just a single REST call, what could possibly go wrong? As it turns out, plenty.

A bunch of people started using the API and I had no way of measuring or knowing that. All I could see was that the servers suddenly started melting and that no matter what I did they wouldn't bloody stop. Turned off everything and the servers were still melting.

Then I remembered that throw-away API offering that got a bit of traction on HackerNews and a tiny bit on Reddit and quite a bit on Twitter. Shut down access to that, stopped the servers from melting and suddenly started receiving emails from disgruntled developers "Hey, I was relying on that API! WTF happened!? How dare you take it off?"

Screw you, you didn't even have the courtesy of telling me that you're using it.

No fault of their own of course, I was the one who's supposed to have developer accounts, throttling, usage quotas and whatnot. The developers just saw a cool API and started using it.

How to properly offer an API

Auth, by oztenphoto

As mentioned before, you are going to need a lot of ... stuff, if you're going to make this a pleasurable experience both for you and your users.

Especially your users.

One way is to build all of the infrastructure yourself - but that takes a lot of time and isn't very sexy at all. Much better to worry about the core problems of your product than making sure some side thing works robustly.

Lucky for you (and your users) there exist a bunch of services whose purpose is making APIs fairly easy and palatable.

The ones I know of are 3scale, Mashape and Mashery.

Essentially all of these services provide stuff like developer keys, a place to host documentation, enforcing rate limits, making sure the right quotas are assigned to the right person, giving you great analytics tools and so on. Basically everything you need to provide a decent API service that keeps developers and your servers happy.

Major differences lie mostly in implementations. While 3scale is something you use server-side and keep asking "Hey, can this user do that? Can they? Right now? Okay!", Mashape and Mashery work as a sort of proxy where they keep track of everything on their own end and only send requests your way when appropriate.

Of course this means you have to conform to some sort of standard that Mashape can understand, but a really cool consequence is that they automatically create client libraries for all sorts of different platforms. And they're the only provider that lets you start charging money right away (by doing it instead of you), so maybe conforming to their ideas of API isn't that bad at all.

I haven't personally used these services before, but I have not-used them ... it's not good.

The next time you offer an API let somebody else take care of it, so you can go back to Making Cool Things (tm) instead of answering the "You offer 1000 requests for free, but I need 1013 and don't want to pay" email for the umpteenth time.

You should follow me on twitter here.

Enhanced by Zemanta