Ask HN: What makes a great API?

https://news.ycombinator.com/item?id=3114682

by frankdenbow • 15 years ago

16 9 15 years ago

news.ycombinator.com

What does it take to make a great API in a developer's eyes? I am doing a talk and would love to get some feedback on the types of things you all think about when choosing APIs to work with.

Some things include documentation, speed to hello world, RESTfulness, simple authentication, aligned incentives, helpful examples, and customer service. What do you think?

billswift2• 15 years ago

From the highest level view:

1) Reliability - it can be counted on to do its job.

2) Consistency - it does it in the same, or at least the same small set of, ways each time.

3) Clarity and Discoverability - it is easy to see or find out what it does.

neinsun• 15 years ago

Documentation?????

billswift2• 15 years ago

I would put adequate documentation as part of clarity and discoverability, both because they serve the same end and because the inherent clarity and discoverability can increase or decrease the amount of documentation needed to effectively use the API. So maybe I should have said "clarity, discoverability, and documentation".

gfox• 15 years ago

Your list is a great place to start. I would add clarity of purpose (too many just say help build back ends)

LeBlanc• 15 years ago

One thing that works great is to build a sandbox tool that lets your users make real API calls with their credentials from your API documentation.

Facebook, Stripe, and WePay have done this. It makes integration much easier when you can test API calls before writing any code.

bmelton• 15 years ago

Documentation & Reliability.

I can suffer through any problem with a remote API so long as the documentation is clear, thorough and contains relevant examples. Stripe's API documentation is about the best I've seen in recent years.

They get bonus points for making the 'cut and paste' examples actually cut and pastable, as they don't have instances of "stripe.com/method/<your_api_key_here>", and instead of have "stripe.com/method/my_actual_api_key", which is super convenient.

Perhaps the only thing that good documentation can't trump is unreliability. This includes (obviously) an API that doesn't always return the right values, or that sometime's fails, but also includes rapidly changing API protocols.

Take the time to think about your APIs early, and try very hard to keep them from changing once they're established. Nobody wants to have to refactor their code because you refactored yours.

karterk• 15 years ago

Others have pretty much summarized my thoughts, but I will add one more to the list: information on rate limiting. The API, if it has rate limits should allow me to track that.

zemo• 15 years ago

Make authoring my own client in my own language straightforward. If you say "see our reference implementation in [some programming language I'm not using]" I'll be very, very irate. This is the kind of thing I'm talking about: http://docs.recurly.com/recurlyjs/signatures/spec/. Expanding on that particularly egregious example: a handful of unit tests is not a specification, and if you want a variety of developers to use your API you can't have its documentation be a set of unit tests. A set of unit tests in a third-party DSL is even worse.

Your documentation should be language agnostic. Everything should be described in regards to HTTP methods, not some aspect of your language, your language's standard library, or, god forbid, some third-party library in your language.

If you DO expect users to rely on a reference implementation, it should be as generic as possible. I'm not a [insert language here] programmer and I don't want to have to learn the ins and outs of [your sandboxing tool] and [your library management tool] and [some fistfull of random third-party libraries] in order to install and run your samples.

Always respond with the requested format, even on errors. Yes, I am advocating that you put a diaper (i.e. a try ... catch block that catches all errors) on your API endpoint. Diapers are generally a bad idea, but if I send you a json request that, for whatever reason, throws a server-side error, please return the error information in a json-parsable manner. django-piston is guilty of not returning json-parsable error pages, and it has the second-most followers of all bitbucker repositories. https://bitbucket.org/jespern/django-piston/wiki/Home

If possible, write sample clients on a variety of popular languages. Put your client on PyPi or RubyGems or npm or Pear or CPAN or whatever, just don't half-ass it.

Know your audience. It's perfectly possible that your target audience doesn't actually give a shit about RESTfulness and they're perfectly happy using SOAP or (gasp!) XML-RPC. Those things may not be "cool" in the buzzwordy world of dynamic scripting languages, but the reality is that they're still standards and yes, people do use them.

Be mindful of how insular HN is and where its interests lie; the HN userbase is representative of the HN userbase, not software developers as a whole. There's a creaking leviathan in the world of "enterprise" software whose foundation lies in things like Java and .NET and where mechanisms like SOAP and XML-RPC are still in use. SOAP is neither useless nor mandatory; it is used by a subset of the software development community, some of whom may be more than willing to give you good money to integrate with their services, if only you'd let them.

kirps• 15 years ago

Documentation and ease of use. The API should function at the highest level possible. I should be able to call the service with concise and powerful statements. The beauty of an API is the ability to quickly build further upon something that has already been done. If I have to go ten rounds with it to get it to work, you've missed the boat.

In that same vein the documentation should be clear and to the point. See Amazon Flexible Payments as an example of what NOT to do. Ambiguous docs with tons of circular linking etc. made me want to kill myself and did end up killing my project. Just my .02.

Ask HN: What makes a great API?

Related Stories