How To Design A Good API and Why it Matters

[@hellowill]

this guy designed many of the JDK classes (the good ones) and worked at Google. Knows his stuff. 43:08 he redesigned stack as arraydeque.. people still using Stack today (literally 15 years after its deprecated) because the naming.

[@5pp000]

"Once you have something that's called a 'set', you know what the operations are. You insert things from [sic] sets, you remove, ..." [23:42] That's like saying "The operations on an 'integer' are incrementing, decrementing, ..." No, those are the operations on an integer _variable_. An _integer_ is, among other things, the _value_ of such a variable at a particular point in the program. It's a pure value; you can't modify 3, you can only cause a variable that currently holds 3 to change its state so it now holds some other integer. If you want, you can create an integer _object_ that holds an integer and is shareable: you can have multiple references to such an object, so that changes in its state are visible via any of those references. But no one would confuse such an object with an integer. Sets are a mathematical concept just like integers. What Joshua Bloch is thinking of (and what his Java Collections Framework incorrectly _calls_ a 'set') is actually a set _object_: a mutable, shareable object whose _value_ is a set. Such an object can hold one set at one time, and a different set at at different time. Here's what I'm getting at. The JCF should have one interface 'Set' that models a pure set value, with no mutating operations, and a second interface 'MutableSet' that extends the first and models a set object, with operations 'add', 'remove', etc. (Similarly, of course, for lists and maps.) Currently, when you're writing some class that contains a mutable set and you want to return a representation of the contents of that set from some method but you don't want to give the caller the ability to reach in and modify it directly, you have to either copy it (ugh) or use 'Collections.unmodifiableSet'; but the latter enforces immutability only at runtime (if the caller tries a mutating operation on the set, an exception is thrown). If there had been two interfaces, you would just have to use 'Set' for the return type of your method rather than 'MutableSet', and immutability would be enforced on the caller statically, at compile time, rather than at runtime. The general lesson I would propose drawing is that if you're designing an API that touches on an area of mathematics -- set theory, in this case -- try to model the mathematical concepts as directly and purely as you can. Make a particular effort to keep implementation concerns separate. You don't have to eliminate them altogether, but try to tease them apart from the math. (This will also help to future-proof your API. In 1997, it wasn't well known how to efficiently implement completely functional collections, where what would once have been a mutating operation now returns a new collection without changing the original one; since then, through the work of people like Chris Okasaki and Phil Bagwell, we know how to do it, and such collections are available in languages like Clojure and Scala.)

[@fredoverflow]

Kotlin has Set/MutableSet, List/MutableList, Collection/MutableCollection and Map/MutableMap where the former are compile-time read-only views on (potentially) mutable versions.

[@PrasannjeetSingh]

Slides can be downloaded from this new link: static.googleusercontent.com/media/research.google.com/en//pubs/archive/32713.pdf

[@hosecoat]

is there a link to the slides, since he ran out of time for the last part?

[@TheF41thfull]

You can get the slides from here. lcsd05.cs.tamu.edu/slides/keynote.pdf

[@geniame]

not any longer :(

[@blargh1234]

www.cs.bc.edu/~muller/teaching/cs102/s06/lib/pdf/api-design

[@DanDascalescu-dandv]

Funny that this is still recommended watching in 2022 by Google recruiting emails, when a lot of these issues have been obsoleted by IDE usage, JSON, and modern languages like TypeScript. Much more commonly important nowadays is the design of REST APIs. BTW, code like that at 45:46 makes me 🤢. And lots of Java code I've seen has been like that. 🤮

[@zaccomusic]

amazing content hope you keep update :)

[@2B_JZA7]

Good job

[@DustinWyatt]

Google for the name of the talk. Looks like the deck is available on slideshare.

[@yogeshchaudhary621]

Top notch content.

[@kyozoku1]

This is definitely 2007. I've been told not to add comment. Which makes me cry......

[@adityamenon]

If he's trolling, he's a master-level player :D

[@ajax_davis]

For anyone interested, we are working on a tool to make API design more efficient, collaborative and robust. apiengine.io - we are taking early registrations for beta!

[@conorc4594]

fantastic!

[@gulgrim]

I'd just like everyone else who reads this man's comment to understand that he is, in essence, kvetching about someone having the audacity to use red to indicate bad, and green to indicate good. That's right. It has absolutely no bearing on this video whatsoever.

[@austinbalaji]

Well, now i know how not to design API :)