Einstein said "Everything should be made as simple as possible, but no simpler" Your misquote means the opposite of what he said.
Re:Ask HN: What makes an API good?
by Someone1234 on Tuesday October 28, 2014 @12:05PM
(#8521659)
Maybe Einstein should have made his quote simplier.
Re:Ask HN: What makes an API good?
by mirekrusin on Tuesday October 28, 2014 @01:55PM
(#8522346)
Can you make it simpler?
Simpler!
Re:Ask HN: What makes an API good?
by ccvannorman on Tuesday October 28, 2014 @12:29PM
(#8521807)
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.
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. :-]
Re:Ask HN: What makes an API good?
by valarauca1 on Tuesday October 28, 2014 @12:39PM
(#8521859)
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
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.
Re:Ask HN: What makes an API good?
by kris-jagasia on Tuesday October 28, 2014 @04:04PM
(#8523237)
this! as a non-technical guy, I can even work with Stripe examples
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.
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.