Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: What makes an API good?

news.ycombinator.com

Post reply on HN
Print view View original

41–50 of 68 posts

Re: Ask HN: What makes an API good?

#41

Post by qeorge »

valarauca1 wrote: post #14

1) URL construction: KISS (Keep It Simple Stupid), or as Einstein said, "Everything should be made as simple as possible, but no simpler." 2) Documentation: Code examples, easy things like: "This is what you send, this is what you get." "If you change this, now you get this." Simple example heavy documentation. 1 example is worth a hundred lines of documentation. 3) Response Time: meh. If your at or around 100ms you…

RE:documentation, Stripe does an awesome thing where they inject your API key and secret into the examples, so you can just copy and paste their example and go.

Its brilliant, and should be copied everywhere!

I'm also a big believer that really excellent, thoroughly commented examples are worth a thousand pages of documentation.

Re: Ask HN: What makes an API good?

#42

Post by sergiosgc »

1. Documentation. It has been said in other comments. If you do nothing else right, do documentation. It is paramount. Documentation must contain code samples that can be ran without scaffolding a huge project. cURL command lines -- or the equivalent in non-HTTP APIs, are, for me, as good as it gets.

2. Account for failure. The failure path is more important than the-one-true-path. Be verbose in your errors. Be specific in your error descriptions. Be extensive in the kinds of error conditions you test, particularly when validating the input. Bonus points here if you can make the API introspectable.

3. Resource oriented. Expose your resources, then verbs on top of that. These are application-level resources. Do not directly expose the data model. RESTful APIs obviously follow this, but going REST is not the only option.

4. Stateless, or with as little state as possible. Stateless APIs make clients a lot simpler. They have the added bonus of scaling better on your end (on the server end).

5. Predictable. This is achieved by being both consistent and verbose. Do not use abbreviations on method names. Define a vocabulary and use always the same nouns to refer to the same entities. If using positional arguments, use the same calling order (i.e. avoid the needle/haystack you see in PHP).

Re: Ask HN: What makes an API good?

#43

Post by patio11 »

First among all things: a good API allows developers to do something enormously useful within their applications which would be prohibitively difficult to do absent the API.

My two favorite APIs are, by a country mile, Twilio and Stripe. They have wonderful documentation, sane design choices, good first-party library support, responsive engineers on standby for questions, curl-able URLs which return human-parseable JSON, yadda yadda, but the most important reason they're my favorite APIs is that they directly enable me to build and sell the things which feed my family.

Re: Ask HN: What makes an API good?

#44

Post by logicuce »

Assuming you take care of the essentials like documentation and code samples, following will make your API shine.

* Explanatory Error Responses: Tell what was wrong in a problematic request and, potentially, how to fix the request

* Introspection end points: Which can tell you more about the request (headers/body) and credentials (rate limits, app id, etc) observed by the server. Is very handy in case of debugging.

* API should be able to tell properly when its unavailable. Ideally by returning proper HTTP 503 response.

Re: Ask HN: What makes an API good?

#45

Post by robbles »

oneeyedpigeon wrote: post #36

My two pet peeves are authentication and rate limiting. Authentication - unless you're dealing with uber-sensitive details, make authentication as straightforward as possible. HTTP basic over SSL works fine for me. Bonus points for authentication-free calls for all your public data that doesn't need to be hidden. If you absolutely must use OAuth, please make sure you implement it to the standard, and - ideally - give…

I'd argue the opposite about rate limiting - If you can add it in a way that allows 95% of valid use cases to never run into it, but stops broken implementations and bad actors from degrading your service, it's a net win for your clients.

I agree it should expose a lot of information though. There's nothing worse than an opaque rate-limit where you can't even predict how to work around it in your code.

Re: Ask HN: What makes an API good?

#46

Post by jedisct1 »

Client libraries.

Release and support good client libraries for popular programming languages.

This is way more important than documenting your API at all.

Nobody likes having to read the gory details of how your API works and having to write a HTTP client around it. And everytime they do, error handling is badly handled, if at all.

People want to start using your service right away. They want to just call one function to do a thing, without having to worry about how it works underneath.

Even if this is not HTTP, think about MySQL. Used everywhere, via tons of different programming languages. Yet virtually no one knows how the protocol ("API") works. And this is completely fine.

Having good client libraries also allows updating the protocol without requiring users to change their apps.

Re: Ask HN: What makes an API good?

#47

Post by ccvannorman »

valarauca1 wrote: post #14

1) URL construction: KISS (Keep It Simple Stupid), or as Einstein said, "Everything should be made as simple as possible, but no simpler." 2) Documentation: Code examples, easy things like: "This is what you send, this is what you get." "If you change this, now you get this." Simple example heavy documentation. 1 example is worth a hundred lines of documentation. 3) Response Time: meh. If your at or around 100ms you…

2) Documentation: Code examples, easy things like: "This is what you send, this is what you get." "If you change this, now you get this." Simple example heavy documentation. 1 example is worth a hundred lines of documentation.

This is the only point that I care about (and 5) for being relevant). SO MANY TIMES I have tried to use an API only to find books of documentation without any working examples. Speak to me in the language your API understands, working examples, and everyone will have a good time. :-]

Re: Ask HN: What makes an API good?

#49

Post by valarauca1 »

ccvannorman wrote: post #47
valarauca1 wrote: post #14

1) URL construction: KISS (Keep It Simple Stupid), or as Einstein said, "Everything should be made as simple as possible, but no simpler." 2) Documentation: Code examples, easy things like: "This is what you send, this is what you get." "If you change this, now you get this." Simple example heavy documentation. 1 example is worth a hundred lines of documentation. 3) Response Time: meh. If your at or around 100ms you…

2) Documentation: Code examples, easy things like: "This is what you send, this is what you get." "If you change this, now you get this." Simple example heavy documentation. 1 example is worth a hundred lines of documentation. This is the only point that I care about (and 5) for being relevant). SO MANY TIMES I have tried to use an API only to find books of documentation without any working examples. Speak to me in t…

Its a major sin a lot of developer commit. I'll just write 400+ pages of documentation.

That's great. Nobody will ever read it. Make it enjoyable to read and interact with. I keep this XKCD over my desk for a reason http://imgs.xkcd.com/comics/manuals.png

Re: Ask HN: What makes an API good?

#50

Post by iamdanfox »

grosskur wrote: post #28

The Heroku platform team has a good document about their API design guidelines: https://github.com/interagent/http-api-design

That is a very comprehensive set of conventions! Contents pasted here:

Foundations - Require TLS, Version with Accepts header, Support caching with Etags, Trace requests with Request-Ids, Paginate with ranges

Requests - Return appropriate status codes, Provide full resources where available, Accept serialized JSON in request bodies, Use consistent path formats, Downcase paths and attributes, Support non-id dereferencing for convenience, Minimize path nesting

Responses - Provide resource (UU)IDs, Provide standard timestamps, Use UTC times formatted in ISO8601, Nest foreign key relations, Generate structured errors, Show rate limit status, Keep JSON minified in all responses

Artifacts - Provide machine-readable JSON schema, Provide human-readable docs, Provide executable examples, Describe stability

Post reply on HN