3 ms·
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: Co
by 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 agoEinstein said "Everything should be made as simple as possible, but no simpler" Your misquote means the opposite of what he said.
- Someone1234 12y agoMaybe Einstein should have made his quote simplier.
- mirekrusin 12y agoCan you make it simpler?
- vange 12y agoSimpler!
- deleted 12y ago[deleted]
- qeorge 12y agoRE: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.
- kris-jagasia 12y agothis! as a non-technical guy, I can even work with Stripe examples
- ccvannorman 12y ago2) 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. :-]
- valarauca1 12y agoIts 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 http://imgs.xkcd.com/comics/manuals.png
- angdis 12y agoYes, 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.