

How APIs should be: Drop in keys, running in 1 minute - merijn481
http://blog.singly.com/2012/05/31/how-apis-should-be-drop-in-keys-and-be-running-in-1-minute/

======
patio11
Apropos of nothing: if one is making decisions based on estimates of probable
conversion rates, my ballpark for "web page visitor -> makes at least one API
request" would be closer to 1/100th of 2% than to 2%. You're probably better
off going for an intermediate conversion ( _cough_ get their email _cough_ )
and then selling them into using the API over time, since this is a thing that
the best prospects won't exactly do on a lark.

(I am unsure of whether I like the make-a-play-in-the-browser-utility
suggestion from the perspective of the business. I have never work directly on
that question for a client, so I don't have even anecdata for y'all on this,
but the developer in me says "That's a great idea! That way I don't have to do
any work to kick the tires." and the marketer in me says "If we sold 'tire
kicking' that would be wonderful now wouldn't it")

~~~
tomgallard
At Pwinty- we collect emails (conversion rate 5-10%), and then try and guide
users through the process.

Firstly- its a great way to engage with users where you might not offer
exactly what they want (do you print canvases, how about xyz). We get most of
our feature ideas from our users wanting something that we don't yet offer.

I also try and schedule in a Skype call with all of our users to understand
exactly what they want from us, and how we can help them (I think this also
convinces them that there's a real person there they can do business with).

Once we've got their emails, we probably convert about 20% into 'making API
calls'. However, I'm expecting that to increase over time (lots of people sign
up, but are just working out how they're going to build their app, rather than
actually doing it).

It's also worth following up non-active users after 1,3 and 6 months. You can
often get useful info that you'd otherwise miss 'we decided not to use you
because x,y,z; we canned the project but are keen to use you in the future
etc)

~~~
patio11
I very much regret that I have only one upvote to give for this comment,
because _every_ API company should be doing that. (Most of the very successful
ones do already, but since many API companies start with two hackers and a
couple of boxes of ramen, you can greatly increase your chance of success by
taking this comment and executing on it.)

------
saurik
> The bottom line is that the single most important step in converting
> developers to permanently use your API in their product is how easy it is
> for them to get started after they sign up.

I take issue with this. If the single most important step to converting
developers to /permanently/ using your API isn't something like scalability,
security, performance, or functionality, there is something wrong with this
world.

Just because you get more people to succeed in trying your API at the
beginning, if it doesn't work for their use case over the long haul they are
just going to leave and do something else: the key word is then "permanently".

In comparison, Amazon's APIs are often ludicrously complex. Even if you try to
use Amazon's client libraries, they are often ludicrously complex, requiring
you to construct object factories to get arguments even for the most common
request paths.

But, by and large, Amazon's services don't stop working when you get too much
data, have well-thought-out authorization mechanisms, have never become
randomly slow as lots of users sign up for the service, and are sufficiently
flexible to support many different kinds of tasks.

The fact that the first time I sat down and used Amazon's APIs it took me a
while to get them working (and that some APIs from them I still haven't gotten
around to learning all the properties of) is then irrelevant: I could tell
they would do what I wanted once I figured it out, and I have never been
disappointed.

Meanwhile, I've come across tons of random startups, often that have websites
that are a "little too Web 2.0" (normally a negative indication for an API
provider, btw), whom have APIs (or libraries, or daemons, or services, or
programming languages) that are great at first but actually sucked.

(I mostly felt the need to make this comment, btw, due to someone else in this
thread seemingly arguing against OAuth because, despite being secure, it made
the API sufficiently complex that they could no longer use curl with it: that
is the opposite method from how you should be choosing an API.)

------
zubairov
Good points are covered in this blog post, however what if we would push it
even further?

Why would people need to download a package? Why would anybody need to learn a
programming language you package designed for (or assume you distribute
packages for many programming language)?

When using APIs for integration or mashups, especially in business world,
person who know how solution should looks like may not have time to code. So
we at <http://elastic.io> think API could be via visual designer.

We believe it's also a way to make API usage _simpler_ for enduser, even the
one who can not, or have no time to code.

~~~
jmathai
We implemented something similar for The OpenPhoto Project where every URL a
user visits is a visual representation of an API endpoint.

My site, for example, is at <http://jmathai.openphoto.me/photos/list>. You can
add ".json" to the end to see the JSON representation of that page.
<http://jmathai.openphoto.me/photos/list.json>. The same rule applies across
the site.

We wrote about it a while back.

[http://blog.theopenphotoproject.org/post/8462620991/clean-
ur...](http://blog.theopenphotoproject.org/post/8462620991/clean-urls-that-
your-users-should-be-able-to-guess)

~~~
zht
this seems like pretty standard REST

~~~
jmathai
It's REST-ish. But the highlight I was hinting at is making the API itself be
more discoverable. We did it by mapping the API directly to the web UI such
that html just becomes the default format type of the API.

------
arethuza
I now know how I like Web APIs to work: Give me the URL and let me go at it
with cURL and some scripts to parse the your JSON.

[Been using the Salesforce REST API recently, and apart from the process of
getting your OAuth token, it's really rather good].

~~~
tluyben2
Yes, I was rather pleasantly surprised with the Pivotaltracker API. I managed
to get it integrated in our hour registration within 30 minutes.

Check; <https://www.pivotaltracker.com/help/api>

All calls have ready cURL examples you can copy/paste and try. Prototyping is
fast.

And no OAuth. OAuth could be good if it were standardized (and thus would work
with a single library without any extra tinkering); it's horrible all over the
place. I understand this fanatical obsession with security and such, but just
make me login and get a token back.

Anyway; Hooray for Pivotal! (Again)

------
DanLivesHere
FYI this is the same org which is running the $10K app challenge using their
API this weekend; <https://singly.com/appchallenge>

------
merijn481
Re-posted to the Factlink blog at <http://blog.factlink.com/>

