7 ms·

Ask HN: What makes an API good?

• metaphorm 12y ago
  Consistency. pick a convention and keep doing things that way, always and everywhere.
• mmmbeer 12y ago
  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...
• richbradshaw 12y ago
  Consistency, predictability, documentation, reliable sample client in a couple of popular languages (e.g. PHP, Python, Ruby), well abstracted.
• zoner 12y ago
  Documentation.
• mguterl 12y ago
  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 12y ago
    Thanks! I will.
• notjosh 12y ago
  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 12y ago
    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.
  • smandadi 12y ago
    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.
• calpaterson 12y ago
  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 12y ago
    been in this position! I feel bad thinking about it now!
• jordanpg 12y ago
  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 12y ago
    >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 12y ago
      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.
  • prottmann 12y ago
    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 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).
• jeff_cressman 12y ago
  Would be great if you shared what you've compiled as well. Thanks.
• mockindignant 12y ago
  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 12y ago
    Thanks!
• massung 12y ago
  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.
• tomp 12y ago
  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).
• valarauca1 12y ago
  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 12y ago
    Einstein said "Everything should be made as simple as possible, but no simpler" Your misquote means the opposite of what he said.
    • Someone1234 12y ago
      Maybe Einstein should have made his quote simplier.
      • mirekrusin 12y ago
        Can you make it simpler?
        • vange 12y ago
          Simpler!
    • deleted 12y ago
      [deleted]
  • qeorge 12y ago
• bvanvugt 12y ago
  Agree with notjosh on this -- so what makes documentation good?
  • nbaleva 12y ago
    In terms of documenting api's, Swagger is your friend : https://helloreverb.com/developers/swagger https://helloreverb.com/developers/swagger
• thom 12y ago
  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.
• angersock 12y ago
  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.
• rfclark 12y ago
  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)
• adelevie 12y ago
  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
• lsjroberts 12y ago
  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
• kevinSuttle 12y ago
  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/
• paulkoer 12y ago
  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
• wging 12y ago
  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.
• grosskur 12y ago
  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 12y ago
    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
• ripberge 12y ago
  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 12y ago
    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 12y ago
      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.
• vmarsy 12y ago
  You can find these slides interesting: http://slideshare.net/guestbe92f4/how-to-design-a-good-a-p-i-and-why-it-matters-g-o-o-g-l-e http://slideshare.net/guestbe92f4/how-to-design-a-good-a-p-i...
• oneeyedpigeon 12y ago
  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 12y ago
    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.
• davidkellis 12y ago
  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.
• dbarlett 12y ago
  I agree with most of Vinay Sahni's points: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api http://www.vinaysahni.com/best-practices-for-a-pragmatic-res...
• jasode 12y ago
  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-success-internal-apis/ http://apievangelist.com/2012/01/12/the-secret-to-amazons-su... [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
• sergiosgc 12y ago
  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 12y ago
    > 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!
• patio11 12y ago
  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.
• logicuce 12y ago
  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.
• jedisct1 12y ago
  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.
• bpedro 12y ago
  I know what makes it bad: http://nordicapis.com/5-reasons-why-developers-are-not-using-your-api/ http://nordicapis.com/5-reasons-why-developers-are-not-using...
• Flenser 12y ago
  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-function-that-creates-something/ http://sheredom.wordpress.com/2014/08/10/how-to-design-api-f... [SHAREDOM-HN] https://news.ycombinator.com/item?id=8160071 https://news.ycombinator.com/item?id=8160071 [FOWLER] http://martinfowler.com/articles/distributed-objects-microservices.html http://martinfowler.com/articles/distributed-objects-microse... [FOWLER-HN] https://news.ycombinator.com/item?id=8172980 https://news.ycombinator.com/item?id=8172980 [LEGO] http://nordicapis.com/legos-api-strategy-resourcing-developers-building-business-case/ http://nordicapis.com/legos-api-strategy-resourcing-develope... [ORLIESAURUS] https://medium.com/@orliesaurus/a-review-of-all-most-common-api-editors-6a720dc4f4e6 https://medium.com/@orliesaurus/a-review-of-all-most-common-... [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-restful-api http://www.vinaysahni.com/best-practices-for-a-pragmatic-res... [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
• CmonDev 12y ago
  NuGet availability is a strong win.
• jgrodziski 12y ago
  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 :-)
• jmakuc 12y ago
  Be strict with your output and promiscuous with your input.
• wheels 12y ago
  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
• onaclov2000 12y ago
  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.
• fosrias 12y ago
  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/
• 3beard 12y ago
  Thread safety. If you write an API never forget that people may want to use it in more than one thread.
• robertlmullen74 12y ago
  The simplest API that could possibly work.