
So you want to offer a public API … - hamax
http://www.zemanta.com/fruitblog/so-you-want-to-offer-a-public-api/
======
tluyben2
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).

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.

~~~
gddr
You said it. I have this feeling people tend to forget developers are users
too. The "don't make me think" rule still applies even if their job is
thinking.

So if you really want people to use your system (API, library, IDE,
programming language, compiler...) you should run usability tests, write easy-
to follow documentation with examples and answers to common problems, make it
super easy to download (if it's software), maybe make a web page where you can
try it online (that helps a lot), have a nice, smooth user interface, make it
behave similar to something users have probably already used, have a good
name, a nice logo, a nice-looking webpage, take care of its search-engine
positioning, offer services such as forums, maybe advertise a bit, sell
shirts, give a free night at a spa to one of the users every month (hey why
not)... wow that list came longer than expected. Well you get the point.

------
stickfigure
This article is bad advice for 99% of startups. It says "your API might become
heavily used, so engineer for it up front".

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."

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:

* 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.

* 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.

* 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.

* 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 _will_ 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.

We (<https://www.voo.st/>) added an API in response to a partner who asked for
it. It took a day, half of which was formatting the documentation
(<https://www.voo.st/developers>). Guess what? It's never been used. Chances
are, your API will be the same way.

------
transmit101
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.

<http://stackoverflow.com/a/975394/62871>

~~~
lucaspiller
I'm not convinced that versioning media-types is the best way. I agree it is a
more correct way as opposed to basically abusing REST, but I think overall
putting the version in the URL is better.

From the linked answer:

> * you break permalinks

> * The url changes will spread like a disease through your interface. What do
> you do with representations that have not changed but point to the
> representation that has? If you change the url, you break old clients. If
> you leave the url, your new clients may not work.

Putting the version somewhere else in the request doesn't fix this. If you
drop support for an old API version it is going to break stuff. It is easier
to spot the issue if you return a 404 rather than a 500 or 400 error, or even
correct data that breaks the app consuming the API as it is expecting
something else.

> * Versioning media types is a much more flexible solution.

The main issue I have with this is I have had the "pleasure" of working with
pretty stupid people implementing clients on my API. They easily get POST and
GET requests mixed up, HTTP and HTTPS, whether or not the request should be
authenticated. I don't want to add something else to confuse them even more...

~~~
MatthewPhillips
> The main issue I have with this is I have had the "pleasure" of working with
> pretty stupid people implementing clients on my API. They easily get POST
> and GET requests mixed up, HTTP and HTTPS, whether or not the request should
> be authenticated. I don't want to add something else to confuse them even
> more...

Where does the madness end? Do you treat everything as though it were GET and
stick the real method (and every other request header) in a query parameter? I
think it's ok to assume a basic level of understanding of one of the best
documented specs in computing.

~~~
lucaspiller
Each to their own I guess. However personally I would rather not spend time
tracking down a "bug" due to a client not consuming my API as documented. If I
can make it easier for them to use, by not doing things the "correct" way,
then I would rather do that.

~~~
j_s
This is often what the pragmatic/practical approach prioritizes (easier for
users), as opposed to the idealistic/academic.

------
mark_h
There's <http://apiaxle.com/> to look at as well, an open-source solution (no
personal experience with it)

------
theatrus2
I run a free service (<http://eve-central.com> \- 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.

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.

~~~
njyx
Very cool :). If it doesn't make sense to monetize it might still at some
point make sense to put sanity limits on some usage - otherwise some high
volume users could end up making you take it down for cost reasons.

Nice problem to have though.

------
Bjoern
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.

[1] <http://zencoder.com/api/>

EDIT: After reading [http://thereisnorightway.blogspot.jp/2011/02/versioning-
and-...](http://thereisnorightway.blogspot.jp/2011/02/versioning-and-types-in-
resthttp-api.html) I am not so sure anymore. They still have quite an awesome
set of examples though.

------
andyjohnson0
Interesting article. I wasn't aware of services like 3scale. Anyone got any
experience of using them?

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.

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.

Documentation is very important. If your API exposes complex data then make
sure that you have good documentation on what every data element means.

~~~
njyx
I'm from 3scale - so factor in any bias filters!) - we definitely think of it
as a contract between the provider and user of the API - could be very
lightweight or heavyweight - but basically it's a bunch of rights on the API
v's a promise of good behavior.

Actually a lot of the APIs that use us are B2B because you often have
different tiers of access rights and limits + want to have approval steps etc.
for sign-ups. These are pain to code yourself.

The change part is a big deal - we normally deal with it in two ways: 1)
launching parallel services for major versions so people consciously migrate
their apps, 2) incremental updates - docs are versioned but all the same calls
work on the same endpoint. How the version is flagged in the call is rather
independent (URL, header, type).

We also use the swagger docs framework (<http://swagger.wordnik.com>) to
create interactive docs to try keep questions on the API itself to a minimum
(people can play with it themselves).

~~~
BerislavLopac
OT: Hi Steven, and please say hi to Josep for me! ;-)

------
arethuza
"The best way to do that is offering it up as a service – a RESTful API even."

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 _not_ going to be a good
idea?

~~~
Swizec
When you're offering to large old-ish enterprises like banks and such you will
likely want to go with SOAP.

When you have a lot of high-speed data, you will want to go with sockets and a
live stream of small bits of data. Like Twitter's firehose for instance, or
getting Wall Street data for your bot trader.

~~~
reidrac
You can have both, and you can do it in a consistent way. Not that you can
make everybody happy, but it's close enough.

For example we implemented our API with both XML-RPC and REST + JSON
interfaces (<http://www.memset.com/apidocs/intro.html>). All the methods are
available and work the same way in both interfaces. There's some extra work to
deal with some of the types (ie. dates in JSON), but it's not too difficult.

So we have one implementation/docs, but two interfaces to access to it.

~~~
BerislavLopac
Actually, the difference between XMP-RPC and REST is not just in the format of
the response, the difference is the whole approach. The way you have described
(didn't go into the docs) you don't have REST at all, just XML-RPC that
returns JSON. Sorry if I misunderstood.

~~~
reidrac
There are two different interfaces for the same implementation. Let me stress
the _different_ part. The RESTful API uses JSON to encode the responses, but
that's all.

Sorry if I didn't explain it very well, the docs are clearer though.

~~~
icebraining
The point is that your RESTful API is not RESTful at all. It's just RPC using
JSON. REST is an architectural style that models the interaction around data
and hypertext instead of actions.

A good rule of thumb is: if the documentation mentions "methods" as anything
other than the uniform ones (if you're using HTTP, that would be GET, POST,
etc), then it's RPC, not REST.

Note: I'm not saying your API is _bad_ ; RPC is a completely valid model. I'm
just saying it's not RESTful.

~~~
reidrac
That's true, we don't use HTTP methods (PUT, GET, POST, DELETE, etc) as part
of the API. In fact we treat POST/GET the same for ease of use.

EDIT: to be fair, in the docs we never say it's a RESTFul API, it was MY
mistake in my first comment.

------
lazyjones
Some more advice here: [http://www.h-online.com/security/news/item/Password-
leak-at-...](http://www.h-online.com/security/news/item/Password-leak-at-
meetOne-1652783.html) ...

------
t_hozumi
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.

