Earlier quoted context omitted.
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?
Ask HN: What makes an API good?
61–68 of 68 posts
Re: Ask HN: What makes an API good?
#62This superficially is about C++, but in practice it's a collection of good advice for APIs in general:
Re: Ask HN: What makes an API good?
#63Re: Ask HN: What makes an API good?
#641) 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…
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
Re: Ask HN: What makes an API good?
#65The 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.
Re: Ask HN: What makes an API good?
#66Well 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/
Re: Ask HN: What makes an API good?
#67Thread safety. If you write an API never forget that people may want to use it in more than one thread.
Re: Ask HN: What makes an API good?
#68The simplest API that could possibly work.