
Ask HN: What makes an API good? - relaunched
I&#x27;ve consumed a great deal of major, public facing APIs over the years, some I&#x27;ve liked more than others. However, I&#x27;m writing a series of APIs for a new project, and ahead of starting I&#x27;ve documented the things I like about some APIs and things I don&#x27;t  about others. For example, uri construction, documentation, response time, flexibility, code samples and organization of taxonomy help me differentiate good and bad.<p>I thought I&#x27;d ask, what do you think makes for a good api?
======
valarauca1
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 don't need to worry to
much. If people want ~50+ calls per second, then ask them what their use case
is, or have them pony up money. Then worry about response time.

4) Flexibility: Largely over rated. You can waste a ton of processing power
trying to figure out what the user _meant_ to say. Most of it is wasted, if
their query doesn't make sense return an error. Your performance will go up.
This hooks into documentation, if your documentation is easy enough to
understand you won't have to fuzz the queries.

5) Code Samples: See documentation.

~~~
onion2k
Einstein said "Everything should be made as simple as possible, but no
simpler" Your misquote means the opposite of what he said.

~~~
Someone1234
Maybe Einstein should have made his quote simplier.

~~~
mirekrusin
Can you make it simpler?

~~~
vange
Simpler!

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

------
notjosh
Documentation is 1000x above anything else. This includes sample project(s).

Documentation is without question the deciding factor of whether I'll use a
service.

Besides that, I care about support channels, adherence to standards (i.e.
correct HTTP status codes), and as few hoops as possible to jump through to
start (i.e. a curl command to get my auth key, and away I go)

~~~
onion2k
Very true, but it needs to be a specific _type_ of documentation - namely
something that explains how to use the API rather than what the API endpoints
are. By sitting down and writing about what's needed to get the most out of
the API, as well as writing extensive code examples, you're forced to think
about how people are going to use the API. Any problems, quirks or bugs should
be obvious at that point _because you 're using the API as it'll be used by
other developers_. Simply listing the endpoints with what parameters they need
and things they'll return won't make your API better.

------
jasode
1) Have the internal team use the same public API as much as possible. I
believe Steve Yegge (of Google and Yahoo) wrote a long article about this
concept. Here's a link[1] but I can't remember if it's the definitive one I
read before. By forcing your internal developers to use the same API, you see
the frustrations of any incoherent designs that outsiders would see. Also, bug
fixes fix the defects for private & public users.

2) Design the API to encourage clients to stumble into the " _pit of success._
" I believe Microsoft's .NET team originated this phrase.[2] This means
sensible defaults for the the most common tasks. It leads to related maxims
such as " _make easy tasks easy and hard tasks possible._ "

3) Additional documentation that's organized thematically around "tasks",
"workflow", "usage scenarios", and "concepts". It's not enough just to have a
dump of functions listed in alphabetical order presented as a "reference
guide". The reference guides are important but people unfamiliar with the new
API need some handholding and reference guides don't do that. The task-
oriented documentation would be things like "Getting Started" or "working
demos".

[1][http://apievangelist.com/2012/01/12/the-secret-to-amazons-
su...](http://apievangelist.com/2012/01/12/the-secret-to-amazons-success-
internal-apis/)

[2][http://blogs.msdn.com/b/brada/archive/2003/10/02/50420.aspx](http://blogs.msdn.com/b/brada/archive/2003/10/02/50420.aspx)

------
massung
Aside from common things like "being useful" the key aspects of a good API (to
me) are:

1\. Expose 2\. Wrap 3\. Consistency

Expose what's going on under-the-hood. For example, an HTTP.Get function may
do what's needed 98% of the time, but if you don't expose requests, sending,
keep-alive, etc. then I won't be able to do the last 2% when I really need it.
Part of exposing is factoring your functions well.

Wrap what's exposed to handle the most common cases. If I want to perform a
GET request, I shouldn't be required to create a request, open a socket, issue
the request, parse the response, follow redirects, etc. There should just be a
simple HTTP.Get function that does all that for me with the common options as
arguments.

Finally, the API should be consistent. Consistency covers a range of topics.
The API should be consistent within itself: consistent naming, modules, etc.
It should be consistent within the environment (e.g. don't use underscored
function names in Go). But consistency also means future releases shouldn't
break existing code unless absolutely necessary.

------
mguterl
You might want to check out The Little Manual of API Design:

[http://www4.in.tum.de/~blanchet/api-
design.pdf](http://www4.in.tum.de/~blanchet/api-design.pdf)

~~~
relaunched
Thanks! I will.

------
angersock
Some things that irk me:

0\. JSON. Use JSON.

1\. Version your API

2\. Any numerical value whose precise value you care about, send as a string.

3\. Any ID should be sent as a string.

4\. Any timestamp should be sent as RFC3339 UTC.

5\. Any data whose numerical value matters (i.e., must properly include NaNs,
whatever) should be sent as an encoded base64 blob.

6\. Properly support HEAD, PUT, PATCH, OPTIONS.

7\. Send back your response as human-readable JSON, with newlines and tabs. If
you can't afford the bandwidth (protip: you _can_ ), then you shouldn't be
using a text format anyways.

8\. Allow me to change replies using accept headers _and_ extensions on the
URI. Document the order of precedence.

9\. Understand the limits of the REST mental model for handling things--don't
be afraid to have a _few_ "ugly" endpoints.

------
jordanpg
One vote for _good_ documentation.

Not just a link to the Javadocs; preferably a "getting started" page that
covers the most common use cases with plenty of plug and play examples (if
such a thing is even possible in your case).

Also, getting back to the API reference, I'm grateful when there is a roadmap
or overview of the class/package structure so I don't have to crawl through
the entire thing.

~~~
kevan
>Not just a link to the Javadocs; preferably a "getting started" page

I wish more java projects had python-style documentation. I can probably
figure out how to do things eventually by wading through Javadocs, but they
can be really frustrating if all I need to know is how to accomplish the core
activity of the project.

~~~
jordanpg
Among some, there is a certain "machismo" associated being able to make do
with the API reference and nothing else. I think this is a waste of time,
personally. I noticed this especially among the Rails developers I've worked
with.

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

------
grosskur
The Heroku platform team has a good document about their API design
guidelines:

[https://github.com/interagent/http-api-
design](https://github.com/interagent/http-api-design)

~~~
iamdanfox
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

------
adelevie
At 18F (a digital services consultancy within the US federal government),
we've drafted API Standards[1]. They're a set of recommendations, rebuttable
presumptions, and bright line rules that we expect our APIs to adhere to. For
an organization that may offer several APIs, having a set of standards will
help ensure, among other things, baseline quality and consistency.

[1] [https://github.com/18f/api-standards](https://github.com/18f/api-
standards)

------
mockindignant
I highly recommend this ~hour long talk given by Josh Bloch a few years ago,
it is quite good and gives plenty of concrete examples:
[https://www.youtube.com/watch?v=aAb7hSCtvGw](https://www.youtube.com/watch?v=aAb7hSCtvGw)

~~~
relaunched
Thanks!

------
paulkoer
I highly recommend the following talk by Joshua Bloch: "How to design a good
API and why it mattes" [1].

Key points:

\- When in doubt, leave it out - you can never remove things from an API but
always add to it.

\- Write several clients of the API to get a good feel how its used. Three is
usually enough, one is not.

[1]
[https://www.youtube.com/watch?v=aAb7hSCtvGw](https://www.youtube.com/watch?v=aAb7hSCtvGw)

------
oneeyedpigeon
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 me a robust client
library in my language of choice.

Rate limiting - ideally, don't. Obviously, this depends on your audience - I
understand why twitter need to rate-limit. Otherwise, be as nice to me as
possible, let me 'save up' calls over time if you can handle the traffic, and
provide me with lots of information about what my limit is, when it will be
reset, etc.

~~~
robbles
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.

------
richbradshaw
Consistency, predictability, documentation, reliable sample client in a couple
of popular languages (e.g. PHP, Python, Ruby), well abstracted.

------
calpaterson
The main thing about creating a good API is that you have a good relationship
and good communication with the consumers of that API. I've seen a lot of
people making internal APIs inside companies treat it as another way to throw
something over a wall.

There's very little universal about a "good" API design. Even response time
might not matter if your users aren't using it synchronously. Best way to make
an API is to have a plan to support old versions, release something early, see
what people make of it and incorporate their improvements. Worst way to make
an API is to try and think of everything before you start - you will fail and
you'll take a long time

~~~
cruisemaniac
been in this position! I feel bad thinking about it now!

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

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

~~~
ironcrucible
> _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._

This is something that I had to deal with just last week. I had been
integrating a 3rd-party API into a business application, and it had very poor
error handling and error descriptions. It wasn't even consistent on when an
endpoint would throw an exception or just return some JSON with an error
message.

To make things worse, I kept running into the same generic error message:
"Something went wrong. Please contact support at support@example.com if it
continues". Of course, that kind of error message doesn't help their support
team, so they could only guess as to what was going wrong. We finally figured
it out after several hours of guessing.

What's strange is that this was an API for a moderately popular Silicon Valley
startup that's marketed to and primarily used by developers.

Please, if you're building an API, don't write these generic messages!

------
fosrias
Well said by many above. Would phrase some thoughts as follows:

1\. Developer Experience (DX) \- How quickly can a developer get up and
running trying the API (ideally immediately). \- Client code generation. \-
How understandable is the API? Does it use common vocabulary or terms you have
to think about what they mean?

2\. Accuracy of documentation \- API and docs in sync. \- Ease of locating
items in the documentation.

3\. Debugabbility \- How easy is it to figure out why requests fail. \- How
easy is it to test edge cases for success/failure and experiment.

4\. Consumer participation in design/prototyping design tools \- Mocking
functionality. \- Collaboration in design that is immediately possible to
test. \- Making it easy to get feedback on different design options.

In the end of the day, good design makes for a good API. And, being able to
involve a variety of stakeholders in the design process in a human-friendly
way is really important to achieve that goal.

As a contributor to ApiBlueprint [1], we have been working to develop a suite
of tools to help all this. I include a link to a sample api blueprint [2] and
to the public documentation/DX portal you get if you import it and render
documentation for it in apiary.io [3].

[1] [http://apiblueprint.org/](http://apiblueprint.org/) [2]
[https://gist.github.com/fosrias/6377469bf0e1d2fd10c7](https://gist.github.com/fosrias/6377469bf0e1d2fd10c7)
[3] [http://docs.sampleapi42.apiary.io/](http://docs.sampleapi42.apiary.io/)

------
mmmbeer
If its a Java or object-oriented framework or library - follow SOLID
principals and limit dependencies. Make it unit testable. Try to make it
consistent - calls to get one type of object should be similar to ways to get
other types of data, etc. Functional approach to the interfaces - pass in
required arguments, get back result. Don't require user/developer to create
several configuration or factory objects before they can call a simple method
to get some data, etc. Don't require the use of dependency injection
frameworks or other complexities. If its web-based API return data as simple
JSON or XML without overly complex namespaces, etc. Name things consistently -
the names of response objects and properties should be the same as the
corresponding inputs, etc. Copy - look at a successful API or library which
does something similar - then copy the way it works and the way its
documented. Especially if the users/developers already know how to use that
one...

------
ripberge
I think it depends upon the use cases of the API, but if you want someone to
be able to build snappy and fast "apps" using your API rather than just
facilitating movement of data in/out for an integration with another piece of
software, I think granularity is important.

Having built our front end using AngularJS, we are the first users of our own
API and that has driven it's design. In order to make things quick, we really
needed to trim down response payloads in some cases which kind of deviates
from standard CRUD patterns in some areas.

This has come at the expense of good documentation (we have a lot more methods
now and having good examples of all of them will be expensive) and consistency
--things are not very uniform anymore. However, as an API consumer I'd rather
have the API give me too many options rather than too little. Our API has gone
from "pretty" to "very functional".

~~~
theblueadept
Sounds like you're going in the wrong direction. An undocumented, granular API
with lots of options won't be used, so it won't matter how fast it is.

~~~
ripberge
So this is why I said it depends upon your use case. We are an enterprise
software company and there are probably less than 50 potential customers in
our target market that could ever use the API.

We are one of the only companies that actually has an API. If a customer has a
use for our API they'll get personalized support.

------
jgrodziski
There was an excellent talk at the last QCon New-York conference about good
API design: [http://www.infoq.com/presentations/API-design-
mistakes](http://www.infoq.com/presentations/API-design-mistakes) Worth watch
it in my opinion :-)

------
lsjroberts
Phil Sturgeon's "Build APIs You Won't Hate" is a fantastic resource. It is
directed towards PHP but the ideas are obviously transferable.

[https://leanpub.com/build-apis-you-wont-hate](https://leanpub.com/build-apis-
you-wont-hate)

------
vmarsy
You can find these slides interesting:

[http://slideshare.net/guestbe92f4/how-to-design-a-good-a-
p-i...](http://slideshare.net/guestbe92f4/how-to-design-a-good-a-p-i-and-why-
it-matters-g-o-o-g-l-e)

------
bpedro
I know what makes it bad: [http://nordicapis.com/5-reasons-why-developers-are-
not-using...](http://nordicapis.com/5-reasons-why-developers-are-not-using-
your-api/)

------
onaclov2000
The ability to use/see the api in action in the page (like maybe a click here
button to see it work), so you can do things like see the network traffic so
you can see what works without having to worry about things like CORS or
whatnot. (my .02)

Also a way to use the api without needing to expose keys, I primarily try to
consume API's using angularJS which is client side only, so giving out my key
can be a problematic experience.

Thus most of my apps I write are for myself, and not others, since this is
very rarely considered.

------
rfclark
If that data is ever to be viewed by a human you should focus on presenting
the data in such a way that it is as easy as possible to display on the
screen, if the process of getting the data to the screen is not easy the vast
majority will either try to find an easier product to work with or just give
up on trying to find a solution to that problem. (IT guys have a lot on their
plate, and mountain of forgotten projects because they didn't have the time)

------
kevinSuttle
Agreed with all the previous comments.

URL Design is key. I often refer to the naming chapter of Uncle Bob's Clean
Code book for this. This also helps with consistency and predictability, which
in turn, makes writing docs easier.

I've got an API Design Readlist, which I've added this thread to.
[http://readlists.com/6c5c6009/](http://readlists.com/6c5c6009/)

------
davidkellis
Ease of use. It should be easy to use. Someone else commented that simple is
what makes an API good. To the extent that a simple API is easy to use, I
agree.

I think an API is no different from any other software product. People like
software that is easy to use. I think an API should be easy to use too. To me,
that's what makes an API good.

------
thom
I like it when APIs offer good filtering options for searches. When all you
have is basically "here is a list of things" \+ "here is a single thing with
an ID", all you end up doing is scraping the entire list to do fun things.

------
wging
Simplicity. As a consumer of your API I should not have to do anything I don't
need to. The worst thing is when you have to jump through hoops to deal with
an API that was clearly designed for the implementer's convenience, not yours.

------
wheels
This superficially is about C++, but in practice it's a collection of good
advice for APIs in general:

[http://doc.qt.digia.com/qq/qq13-apis.html](http://doc.qt.digia.com/qq/qq13-apis.html)

------
dbarlett
I agree with most of Vinay Sahni's points: [http://www.vinaysahni.com/best-
practices-for-a-pragmatic-res...](http://www.vinaysahni.com/best-practices-
for-a-pragmatic-restful-api)

------
tomp
Versioning. Also, make sure that you're committed to supporting old versions
of your API for the foreseeable future (the actual time period depends on the
company - for Google, 20-30 years, while 3-5 years for a startup).

------
jeff_cressman
Would be great if you shared what you've compiled as well. Thanks.

------
Flenser
You may find some of these helpful:

• Web API Design Crafting Interfaces that Developers Love - eBook [APIGEE]

• How to design an API function that creates something [SHAREDOM] [SHAREDOM-
HN]

• Microservices and the First Law of Distributed Objects [FOWLER] [FOWLER-HN]

• Lego’s API Strategy: Resourcing Developers and Building a Business Case
[LEGO]

• A review of all most common API editors — Medium [ORLIESAURUS] [ORLIESAURUS-
HN]

• Best Practices for Designing a Pragmatic RESTful API [VINAYSAHNI]
[VINAYSAHNI-HN1] [VINAYSAHNI-HN2]

• Best practices for API versioning? - Stack Overflow [SO] [SO-HN]

• Designing Hypermedia APIs [KLABNIK]

[APIGEE] [https://pages.apigee.com/web-api-design-
ebook.html](https://pages.apigee.com/web-api-design-ebook.html)

[SHAREDOM] [http://sheredom.wordpress.com/2014/08/10/how-to-design-
api-f...](http://sheredom.wordpress.com/2014/08/10/how-to-design-api-function-
that-creates-something/)

[SHAREDOM-HN]
[https://news.ycombinator.com/item?id=8160071](https://news.ycombinator.com/item?id=8160071)

[FOWLER] [http://martinfowler.com/articles/distributed-objects-
microse...](http://martinfowler.com/articles/distributed-objects-
microservices.html)

[FOWLER-HN]
[https://news.ycombinator.com/item?id=8172980](https://news.ycombinator.com/item?id=8172980)

[LEGO] [http://nordicapis.com/legos-api-strategy-resourcing-
develope...](http://nordicapis.com/legos-api-strategy-resourcing-developers-
building-business-case/)

[ORLIESAURUS] [https://medium.com/@orliesaurus/a-review-of-all-most-
common-...](https://medium.com/@orliesaurus/a-review-of-all-most-common-api-
editors-6a720dc4f4e6)

[ORLIESAURUS-HN]
[https://news.ycombinator.com/item?id=8505244](https://news.ycombinator.com/item?id=8505244)

[SO]
[http://stackoverflow.com/a/398564/2541](http://stackoverflow.com/a/398564/2541)

[SO-HN]
[https://news.ycombinator.com/item?id=7350432](https://news.ycombinator.com/item?id=7350432)

[VINAYSAHNI] [http://www.vinaysahni.com/best-practices-for-a-pragmatic-
res...](http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api)

[VINAYSAHNI-HN1]
[https://news.ycombinator.com/item?id=6624229](https://news.ycombinator.com/item?id=6624229)

[VINAYSAHNI-HN2]
[https://news.ycombinator.com/item?id=5819231](https://news.ycombinator.com/item?id=5819231)

[KLABNIK]
[http://www.designinghypermediaapis.com/blog/index.html](http://www.designinghypermediaapis.com/blog/index.html)

------
3beard
Thread safety. If you write an API never forget that people may want to use it
in more than one thread.

------
zoner
Documentation.

------
metaphorm
Consistency. pick a convention and keep doing things that way, always and
everywhere.

------
bvanvugt
Agree with notjosh on this -- so what makes documentation good?

~~~
nbaleva
In terms of documenting api's, Swagger is your friend :
[https://helloreverb.com/developers/swagger](https://helloreverb.com/developers/swagger)

------
jmakuc
Be strict with your output and promiscuous with your input.

------
robertlmullen74
The simplest API that could possibly work.

------
CmonDev
NuGet availability is a strong win.

