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

31–40 of 68 posts

Re: Ask HN: What makes an API good?

#31

Post by Someone1234 »

onion2k wrote: post #19
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…

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.

Re: Ask HN: What makes an API good?

#32

Post by [deleted] »

onion2k wrote: post #19
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…

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

[deleted]

Re: Ask HN: What makes an API good?

#33

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

Re: Ask HN: What makes an API good?

#34

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

Re: Ask HN: What makes an API good?

#36

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

Re: Ask HN: What makes an API good?

#37

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

Re: Ask HN: What makes an API good?

#39

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

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

Re: Ask HN: What makes an API good?

#40

Post by prottmann »

jordanpg wrote: post #7

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.

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

Post reply on HN