Don't forget to offer PLENTY of immediately usable examples of the API. Like Pivotaltracker has copy/paste-able curl commands to try out the API. Have libs with consistent examples for all popular (and, if for some free PR, less popular languages). Version your API in the URL; you might need large changes to existing stuff, so you cannot trust on backward compatibility all the time while it is really annoying for devs when something works if they have to change it (or it stops working).<p>Edit; hire 'average' programmers from oDesk etc to build 'stuff' against it 'for clients' (threat it as a serious project) to figure out how easy it REALLY is to make things with it. Average programmers are, well, the average, so they will be the most likely consumers of your API. If they have no clue at all, you didn't go far enough perfecting everything. For instance we hired a bunch of devs to do a Windows plugin for our monitoring system and we found out our documentation and examples were completely unusable for them. We'll have to rewrite/refactor all of that and have them re-try.
This article is bad advice for 99% of startups. It says "your API might become heavily used, so engineer for it up front".<p>I have an alternative suggestion: "Your API (even more so than your product) is most likely never going to be used by anyone, so engineer to get it out the door as quickly as possible and test the waters."<p>Authorization, throttling, quotas, and monetization are all things you can worry about in the happy-but-unlikely case that your API takes off. In the mean time, just get it out the door. There are some things you can do to future-proof yourself with zero effort:<p>* Require every request to submit a contact email address as a parameter. This gives you a crude way to find out who is using your API and how much, and gives you the ability to contact them when you make breaking changes. Clients who don't submit contact information have nobody to blame but themselves when you make breaking changes.<p>* Put your API on a different domain from your main site, ie api.example.com instead of www.example.com. This gives you more flexibility to move it around without breaking things.<p>* Documentation is critical, but easy - provide examples. Just a series of "Want to do X? Formulate a link like this" and make a real link that actually works.<p>* Don't overthink the API. Yeah, use REST principles and don't be a total idiot. But accept that your first API is just an experiment. If your API is successful, you <i>will</i> end up rewriting it. The most important things are that 1) it works, 2) it's useful, and 3) users can figure out how to use it from the documentation. Just get something out there, even if it isn't pretty. If you need to make breaking changes, that's what the contact email is for.<p>We (<a href="https://www.voo.st/" rel="nofollow">https://www.voo.st/</a>) added an API in response to a partner who asked for it. It took a day, half of which was formatting the documentation (<a href="https://www.voo.st/developers" rel="nofollow">https://www.voo.st/developers</a>). Guess what? It's never been used. Chances are, your API will be the same way.
Please, please don't help to persist the convention of putting the API version number in the URL. There are far better ways of doing it.<p><a href="http://stackoverflow.com/a/975394/62871" rel="nofollow">http://stackoverflow.com/a/975394/62871</a>
There's <a href="http://apiaxle.com/" rel="nofollow">http://apiaxle.com/</a> to look at as well, an open-source solution (no personal experience with it)
I run a free service (<a href="http://eve-central.com" rel="nofollow">http://eve-central.com</a> - I am not a designer ;)) which has an open API - no rate limits, no accounts, no signups, etc. Yes, technically this is bad, and has had interesting implications for support (some APIs date back to 2007 without any changes), but in this case is the right choice. It works by throwing enough power behind it, and relying on caches. The API is popular for its audience - approximately 50+ million calls per month, which easily outnumbers the (ad supported) web front end pageviews.<p>Due to licensing of content, it would be iffy to monetize directly (technically even the ads are in violation of that), so I don't even consider it.
The best API design I have come across so far is from Zencoder [1]. Their documentation is spot on and they also have a nice little API builder. I found it interesting to study while doing designs for our own API.<p>[1] <a href="http://zencoder.com/api/" rel="nofollow">http://zencoder.com/api/</a><p>EDIT: After reading <a href="http://thereisnorightway.blogspot.jp/2011/02/versioning-and-types-in-resthttp-api.html" rel="nofollow">http://thereisnorightway.blogspot.jp/2011/02/versioning-and-...</a> I am not so sure anymore. They still have quite an awesome set of examples though.
Interesting article. I wasn't aware of services like 3scale. Anyone got any experience of using them?<p>I developed, and am responsible for, a moderately complex b2b web API that is been in use for about three years. A b2b API embodies a contract between organisations, and it's important to understand that this is different to b2c (e.g. Twitter) which is less restrictive.<p>The biggest issue for me has been dealing with change. User requirements change. The underlying system changes and accretes new features that need to be exposed in the API. How to deal with this without either compromising the integrity of the API's design or (at the other extreme) breaking systems that use the API, is not easy. I don't know of any easy answers, but design your URLs and data schemas with versioning in mind and get to know the developers who use your API.<p>Documentation is very important. If your API exposes complex data then make sure that you have good documentation on what every data element means.
"The best way to do that is offering it up as a service – a RESTful API even."<p>I must admit to being a big fan of RESTful APIs, but I'm skeptical of treating any technical approach as being universally applicable. Are there any likely scenarios where a RESTful API for a web service is <i>not</i> going to be a good idea?
Some more advice here: <a href="http://www.h-online.com/security/news/item/Password-leak-at-meetOne-1652783.html" rel="nofollow">http://www.h-online.com/security/news/item/Password-leak-at-...</a> ...
I think versioning API is an illusion.
It is all source of complexity that eventually kills us.
Give up keeping exactly the same behavior as actual models change.