

How to Design Great APIs [video] - csmajorfive
http://blog.parse.com/2013/10/02/parse-developer-day-video-series-how-to-design-great-apis/

======
stiff
This is such a shallow view of the topic. If you do good software engineering,
all your programs also make great APIs for their problem domain, and there is
only a few new things you need to learn about deploying them more widely if
you fancy doing so. Making a great API is simply writing a great program, and
here is what you have to go through to make one:

\- 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://www.cs.umd.edu/class/spring2003/cmsc838p/Design/criteria.pdf)

[http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.136...](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.136.8193&rep=rep1&type=pdf)

[http://www.cs.cornell.edu/courses/CS4860/2012fa/Supplemental...](http://www.cs.cornell.edu/courses/CS4860/2012fa/Supplemental%20Notes%20lec-26-3.pdf)

And some modern classics:

[http://www.stepanovpapers.com/](http://www.stepanovpapers.com/)

[http://www.cs.ox.ac.uk/people/richard.bird/](http://www.cs.ox.ac.uk/people/richard.bird/)

Maybe we will live to see times when software engineering is a real
profession...

~~~
lacker
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 ;-)

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

~~~
splicer
If I'm writing a system library in C, I'm supposed to somehow make it RESTFUL?

~~~
nfoz
It's weak, but you might consider strtok() to be less restful than strlen()
because it isn't stateless.

------
BadassFractal
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](https://www.parse.com/questions/unique-fields--2) ) that will obviously not
work, I'm just going to pass on this one.

------
gingerlime
I'm not convinced laziness is an emotion.

Even though I suppose you can say "I feel lazy today".

~~~
lacker
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=20110907054828AAMHaQl)

~~~
gingerlime
I stand corrected. Was probably overcome with lazy emotions that prevented me
from doing any actual work to find out :)

------
cryon
So if I understand this correctly, great API design is all about naming
conventions! Sounds easy enough!

