So you want to offer a public API …

API, by thesmith
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
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 ™ 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

Subscribe to newsletter

  • Pingback: 12 Most Trending Zemanta Posts from 2012 (You Should Read before 2013) - Zemanta Blog

  • Pingback: Web Technology Roundup | crackedhorizon

  • http://thomasdavis.github.com/ Thomas Davis

    For anyone interested, we are working on  a tool to make API design more efficient, collaborative and robust.

    http://apiengine.io – we are taking early registrations for beta!

  • http://thomasdavis.github.com/ Thomas Davis

    For anyone interested, we are working on  a tool to make API design more efficient, collaborative and robust.

    http://apiengine.io – we are taking early registrations for beta!

  • Pingback: Building A Paid API Offering | Blog - Semantics3

  • Pingback: Building A Paid API Offering | Blog - Semantics3

  • Pingback: This Week in #REST – Volume 44 (Apr 4 2012 – Aug 24 2012) « This week in REST

  • Pingback: This Week in #REST – Volume 44 (Apr 4 2012 – Aug 24 2012) « This week in REST

  • http://catwell.info/ Pierre Chapuis

    Maybe the author thinks support is the most important thing because he has actual experience providing a for-profit API to real users (customers, actually). I emphasize the “for-profit” because it means you can not afford to just say “stupid user, you don’t get it, just RTFM some more or go away”.

    Making client libraries may help a little, but what it does is mostly move the problem from “how do I call your REST-(ful|ish) API”  to “how do I use your client for iOS, I swear I have stared at your documentation for at least 3 whole minutes, and what is the XCode thing by the way, and are you sure you can scale because I am sure I am *way* bigger than anybody that has ever used your API before”.

    Regarding versioning, maybe adding the version in the URL (ie. making a separate endpoint for each version) is bad but then why is *everybody doing it*, big players (Twitter) and API role models (Twilio, Stripe) alike? I will tell you why: because it is the simplest thing that works. The simplest thing for you and for your users. Way better than versioned media types, anyway. And in 9x% the code to consume your API is going to be written by humans, not machines, so the right thing to do is make it simple for them.

    The dream of completely automated machine consumption is a good thing, sure, but REST is nowhere close to it. And people singing its praise are usually the ones bashing old-school Web Services (WS-*) framework which, despite all its inelegance and convoluted complexity, was one of the closest things to full automation that ever existed (with WSDL / UDDI).

  • http://catwell.info/ Pierre Chapuis

    Maybe the author thinks support is the most important thing because he has actual experience providing a for-profit API to real users (customers, actually). I emphasize the “for-profit” because it means you can not afford to just say “stupid user, you don’t get it, just RTFM some more or go away”.

    Making client libraries may help a little, but what it does is mostly move the problem from “how do I call your REST-(ful|ish) API”  to “how do I use your client for iOS, I swear I have stared at your documentation for at least 3 whole minutes, and what is the XCode thing by the way, and are you sure you can scale because I am sure I am *way* bigger than anybody that has ever used your API before”.

    Regarding versioning, maybe adding the version in the URL (ie. making a separate endpoint for each version) is bad but then why is *everybody doing it*, big players (Twitter) and API role models (Twilio, Stripe) alike? I will tell you why: because it is the simplest thing that works. The simplest thing for you and for your users. Way better than versioned media types, anyway. And in 9x% the code to consume your API is going to be written by humans, not machines, so the right thing to do is make it simple for them.

    The dream of completely automated machine consumption is a good thing, sure, but REST is nowhere close to it. And people singing its praise are usually the ones bashing old-school Web Services (WS-*) framework which, despite all its inelegance and convoluted complexity, was one of the closest things to full automation that ever existed (with WSDL / UDDI).

  • Rob
  • Rob
  • Rashid Omar

    Very very insightful. 

  • Rashid Omar

    Very very insightful. 

  • nbevans

    You forgot to mention the two biggest ones that should be on your list:

    1. A versioning strategy. Hint: adding 2.0 etc to your so-called “RESTful” URL is *not* a proper versioning strategy.
    2. Client libraries available as open source projects in numerous popular languages like .NET, RoR, Python, PHP etc.

    Not sure why you think support is more important than these.

  • nbevans

    You forgot to mention the two biggest ones that should be on your list:

    1. A versioning strategy. Hint: adding 2.0 etc to your so-called “RESTful” URL is *not* a proper versioning strategy.
    2. Client libraries available as open source projects in numerous popular languages like .NET, RoR, Python, PHP etc.

    Not sure why you think support is more important than these.

  • Michael Chermside

    In addition to  3scale, Mashape and Mashery, another great one is Apigee (http://apigee.com/).

  • Michael Chermside

    In addition to  3scale, Mashape and Mashery, another great one is Apigee (http://apigee.com/).

  • http://twitter.com/njyx Steven Willmott

    Great post – and thanks for the mention (3scale!) – too true that a lot of these issues turn out to be much more of a pain than expected. 
    Another factor is handling support queries on the API (“do you have a param to allow me to …”, “I can’t get my call XYZ to work…”) – there’ll always be some of that to handle, but using something like Swagger (http://swagger.wordnik.com) which we integrate in the platform also creates interactive documentation pages which hopefully allow people to answer a lot of their questions themselves without having to email you!

    Great post!

  • http://twitter.com/njyx Steven Willmott

    Great post – and thanks for the mention (3scale!) – too true that a lot of these issues turn out to be much more of a pain than expected. 
    Another factor is handling support queries on the API (“do you have a param to allow me to …”, “I can’t get my call XYZ to work…”) – there’ll always be some of that to handle, but using something like Swagger (http://swagger.wordnik.com) which we integrate in the platform also creates interactive documentation pages which hopefully allow people to answer a lot of their questions themselves without having to email you!

    Great post!

  • nuwanbando

    Great read :) 

    have you tried the API Manager from WSO2 {http://wso2.com/products/api-manager}

  • nuwanbando

    Great read :) 

    have you tried the API Manager from WSO2 {http://wso2.com/products/api-manager}