How to Design Great APIs [video](blog.parse.com)
blog.parse.com
How to Design Great APIs [video]
http://blog.parse.com/2013/10/02/parse-developer-day-video-series-how-to-design-great-apis/
8 comments
Yeah I think these are some pretty good points. I think giving a talk is just naturally a bit more shallow than research papers can be. I was hoping to spur some peoples' interest and get some conversations going and if that ends up in more people getting deeply interested and reading things like the papers you link to in more depth, that would be great. Thanks for watching ;-)
A breakthrough API can also come through finding a simpler representation/model for some subset of the problem space.
How to design a great API:
1) Give me some very very valuable data that can help my business. (90% of it)
2) Ensure reliability and uptime (9% of it)
3) Make it RESTFUL and have good documentation (1% of it).
The I in API is for interface - 1 and 2 are just about having a great web service :)
I'd consider Salesforce to have #1 and #2, but pretty sure no one who's used their API would call it "great".
4) Don't use SOAP (the other 90% of it.)
I'm not sure I'd use Parse as a point of reference for much of anything, especially not as a shining beacon of software engineering.
After the 4-5 hour outage a few months ago which tanked more than one person's app launch, and their amusing attempts at providing "workarounds" (e.g. see this: https://www.parse.com/questions/unique-fields--2 ) that will obviously not work, I'm just going to pass on this one.
After the 4-5 hour outage a few months ago which tanked more than one person's app launch, and their amusing attempts at providing "workarounds" (e.g. see this: https://www.parse.com/questions/unique-fields--2 ) that will obviously not work, I'm just going to pass on this one.
I'm not convinced laziness is an emotion.
Even though I suppose you can say "I feel lazy today".
Even though I suppose you can say "I feel lazy today".
I was concerned about this while preparing for the talk. However, my research turned up strong evidence that laziness is indeed an emotion:
http://ph.answers.yahoo.com/question/index?qid=2011090705482...
http://ph.answers.yahoo.com/question/index?qid=2011090705482...
I stand corrected. Was probably overcome with lazy emotions that prevented me from doing any actual work to find out :)
So if I understand this correctly, great API design is all about naming conventions! Sounds easy enough!
- You identify the best set of data and the best abstractions to represent whatever your program is modelling. This is a tricky conceptual part that often requires deep thought and sometimes several rewrites. You can represent a point in space as a triple of separate coordinates, but you will collapse under the mess of details if you try to build a 3D engine this way, and keep in mind this representation was already a revolution in thinking over the approach of the ancient Greeks, one that took mankind more than a thousand years and kickstarted calculus and then modern physics.
Good abstractions can simplify thinking so much as to allow doing completely new things, but they can also be very hard to find. I think linear algebra, which is what makes the 3d engine doable, is one of the more beautiful examples of this and one that should be studied carefully by prospective software engineers. It also isn't something that only comes up doing very sophisticated things, in the most mundane applications choosing a different set of variables to represent state might produce a revolutionary simplification. If you fail to do this step well, there is no way you are going to produce a good program, and frequently you won't produce nothing at all. An API that exposes wrong abstractions will be clunky to use no matter what else you do.
- You identify the constraints that make the data meaningful. A point on the screen might be represented by integers: x and y describing the position, and r, g and b describing the colors, but not all tuples of 5 integers will be valid representations of a point on the screen.
- You specify a set of operations preserving those constraints. You choose the names for those operations carefully. You make the argument list easy to remember. You make the most common use case the default one. You think carefully about which information is useful enough to return. You respect the conventions of the domain you are operating in. You use consistent naming. You write tests making sure your operations don't violate those constraints. ..., this is a whole craft to learn.
- You look for the best distribution and division of this data and operations into individual classes/modules. This again takes a lot of experimentation. You never, ever, EVER mix the abstract model of the problem domain with the messy details of what goes on the screen, with database accesses, with external API calls etc.
All this is not a sequential process, the activities have to be done repeatedly and in various order and you almost always need several attempts. Identify data, find abstractions, apply constraints, find a way to ensure operations preserve constraints - everything that was done in software engineering revolves around this, aspect oriented programming, design by contract, TDD, structured programming, formal methods, OOP, FP, generic programming, ...
However you approach it, you not only want to end up with a correct program that does what you want it to do, but also with a clear language that expresses the problem you are solving. Then your program is easy to understand for you and for others, hence more likely to be bug-free, easy to maintain and modify, and easy to expose as an external API.
Read some classic papers:
http://www.cs.umd.edu/class/spring2003/cmsc838p/Design/crite...
http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.136...
http://www.cs.cornell.edu/courses/CS4860/2012fa/Supplemental...
And some modern classics:
http://www.stepanovpapers.com/
http://www.cs.ox.ac.uk/people/richard.bird/
Maybe we will live to see times when software engineering is a real profession...