Ask HN: What makes an API good? | Hacker News Reader

Ask HN: What makes an API good?

67 pointsrelaunched66 comments

I've consumed a great deal of major, public facing APIs over the years, some I've liked more than others. However, I'm writing a series of APIs for a new project, and ahead of starting I've documented the things I like about some APIs and things I don't about others. For example, uri construction, documentation, response time, flexibility, code samples and organization of taxonomy help me differentiate good and bad.

I thought I'd ask, what do you think makes for a good api?

View on HN

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.

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

Maybe Einstein should have made his quote simplier.

Can you make it simpler?

Simpler!

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.

this! as a non-technical guy, I can even work with Stripe examples

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

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

Yes, examples are critical. It is possible, however, to make the examples TOO simple. I've seen this a lot in the documentation for libraries in the programming language R. The examples are so stripped down and abstracted from what you would use in actual work that you can't see how to apply them in a useful situation.

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.

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)

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.

How much documentation did you get, when you got your Mercedes Car. The stress on Documentation is a little overrated in my humble opinion. If the Tools are made intuitive and the API is made as a natural way of thinking and progression of the state of the Message, The API speaks for itself, and the Developers engagement would be at its peak. If you have to read a Documentation before applying your Brakes on a car, you might as well be too late. Adherence to Standards and not letting unexpected happen and get out of the way of the developers work process is the way to go.

Having said that, If you are on the leading edge of software which no one has attempted before, or trying to create a Market, Thats when your Documentation would explain those edge cases better to gain appreciation of your point of view.

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

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

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.

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

http://www4.in.tum.de/~blanchet/api-design.pdf

Thanks! I will.

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.

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.

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

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.

He talks primarily about a REST-Api not Code-Api. For Code-Api i prefer Javadoc too.

For rest-api https://github.com/apidoc/apidoc

Within the doc you can add examples for usage and response.

But a some common pages with Tutorials / HowTos are nice and should be added to a good documentation. (it depend on the complexity of your project and your audience).

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.

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

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

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

Thanks!

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

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.

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.

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

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

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

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.

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

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

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/ [2] https://gist.github.com/fosrias/6377469bf0e1d2fd10c7 [3] http://docs.sampleapi42.apiary.io/

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

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

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.

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.

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

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

You can find these slides interesting:

http://slideshare.net/guestbe92f4/how-to-design-a-good-a-p-i...

I know what makes it bad: http://nordicapis.com/5-reasons-why-developers-are-not-using...

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.

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)

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/

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.

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.

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.

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

I agree with most of Vinay Sahni's points: http://www.vinaysahni.com/best-practices-for-a-pragmatic-res...

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

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

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

[SHAREDOM] http://sheredom.wordpress.com/2014/08/10/how-to-design-api-f...

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

[FOWLER] http://martinfowler.com/articles/distributed-objects-microse...

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

[LEGO] http://nordicapis.com/legos-api-strategy-resourcing-develope...

[ORLIESAURUS] https://medium.com/@orliesaurus/a-review-of-all-most-common-...

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

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

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

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

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

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

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

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

Documentation.

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

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

In terms of documenting api's, Swagger is your friend : https://helloreverb.com/developers/swagger

Be strict with your output and promiscuous with your input.

The simplest API that could possibly work.

NuGet availability is a strong win.

Reply on news.ycombinator.com