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)
Ask HN: What makes an API good?
21–30 of 68 posts
Re: Ask HN: What makes an API good?
#22At 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.
Re: Ask HN: What makes an API good?
#23One 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.
Re: Ask HN: What makes an API good?
#24Phil Sturgeon's "Build APIs You Won't Hate" is a fantastic resource. It is directed towards PHP but the ideas are obviously transferable.
Re: Ask HN: What makes an API good?
#25Agreed 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/
Re: Ask HN: What makes an API good?
#26I 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.
Re: Ask HN: What makes an API good?
#27Simplicity. 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.
Re: Ask HN: What makes an API good?
#28The Heroku platform team has a good document about their API design guidelines:
Re: Ask HN: What makes an API good?
#29One 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.
Re: Ask HN: What makes an API good?
#30Consistency. pick a convention and keep doing things that way, always and everywhere.