

Ask HN: What makes you adopt an API? - mingyeow

What are the key factors for developers to start adopting your API if you offer one?<p>There are so many things they can do - how and why will they spend the time and effort to integrate your API?<p>Conversely, what "excites" you enough to jump an at API?
======
mahmud
Deja vu! You asked the same question 11 hours ago?

<http://news.ycombinator.com/item?id=640944>

Also, what sort of API are we talking about here? I want different things in a
compiler backend API (IR) than I do in a GUI toolkit or remote procedure call
or a web service.

Most important thing in all is portable data representation. I want to be able
to create and consume the data in any language or tool, so don't ask me to
fill a buffer in memory and wait. More message passing, less shared memory,
unless you're the OS kernel, and even then ..

------
hboon
Depends on the right combination of usefulness and simplicity.

I'm assuming this is web-based. Here's something practical at the
implementation level:

1\. It doesn't have to be true REST-ful. But it should be as easy as forming a
GET URL string, or if appropriate, POST with simple, string payloads unless it
is binary data like images etc. i.e. no XML attachments please. Twitter,
Posterous are good examples of these.

2\. Return results in JSON and XML. Prefer JSON. It is easier and more
efficient (yes, it's a hunch, no benchmark done) to get a dictionary/hashmap
from a JSON string rather than XML. And the quickest way if I want to use such
an API quickly and easily is to load the results into a dictionary/hashmap and
grab values from there. Twitter is good here.

3\. If you provide the API with results in more than 1 format make sure they
work the same. The Twitter API is a great example of what your API should not
be.

4\. Make sure they work. At least fix them quickly, this is a web-based API,
and web-based means they can be fixed quickly. The Twitter API is a great
example of what your API should not be.

5\. Give developers enough time and warning when you make breaking changes.
The Twitter API is an example of what it should not be. Posterous is a great
example of what it should be.

6\. Don't make me get a developer key/ID please.

7\. Versioning. Don't bother. Yet.

------
makecheck
In addition to doing what I want, I appreciate APIs that make reasonable
attempts at backward compatibility and clearly document their plans for
changes (e.g. deprecation); this shows that the API providers respect their
developers' investments.

I also like canonical/primitive APIs. Functions with side effects drive me
crazy, especially if they're poorly documented and there is no other apparent
way to achieve a goal.

A lesser consideration is how pretty the API is. While functionality comes
first, I grow quickly frustrated with APIs that can't even be consistent
within themselves (e.g. function doThis() and do_that() in the SAME CLASS), or
APIs that are not really taking advantage of the conventions and capabilities
of the language they're in (e.g. a C++ API that decides to write its own
string class that _does not_ add anything over the standard class).

------
noodle
#1 - functionality. if it doesn't do something i'm interested in using, i
won't use it.

#2 - ease of use. if its ridiculously complex, i'll still probably use it, but
i'd jump ship for something easier if something were to arise. simplicity =
productivity.

------
dannyr
Good documentation.

Sample Apps.

Client Libraries for popular languages (e.g. Python, Ruby, .Net, etc.)

