How To Design A Good API and Why it Matters

Google Tech Talks
January 24, 2007
ABSTRACT
Every day around the world, software developers spend much of their time working with a variety of Application Programming Interfaces (APIs). Some are integral to the core platform, some provide access to widely distributed frameworks, and some are written in-house for use by a few developers. Nearly all programmers occasionally function as API designers, whether they know it or not. A well-designed API can be a great asset to the organization that wrote it and to all who use it. Good APIs increase the pleasure and productivity of the developers who use them, the quality of the software they produce, and ultimately, the corporate bottom line....

[@Abdullah-mg5zl]

*Here is a brief summary:* Getting the requirements for your API: -extract "true requirements" from your customers (often, customers give you solutions as requirements, when they should be giving you a problem) -extract requirements in the form of use cases (i.e. "as a shopper, i want to be able to add items to my cart") -create a small specification (about one page) and create it fast. Then present it to your customers for feedback, modify, and repeat. In other words, create the specification in an "iterative" manner (with constant feedback from your customer) Writing the API: -make your classes/functions small and cohesive. If its hard to name, its doing too much. -name, name, name. Naming is everything. Better names, makes your API easier to learn/use. -use the conventions/idioms/patterns that are common in whatever language/platform your API is meant to be used on. This reduces the amount your clients have to learn in order to use your API. -document every single class/function. For a class, what does it represent? For a function, what does it do, what are its pre/post conditions and does it have any side effects? -keep everything as private as possible (private classes/member functions/fields) -design your API with change in mind. You will not get it perfect the first time. Try to keep that in mind when designing your API and you're more likely to design it in such a way that it can evolve/adapt later when needed. -"when in doubt, leave it out", if you're not sure about adding something to your API, don't. You can always add later when you are SURE. If you add it now, when your not sure, you may get it wrong, now your clients are using that wrong API and you can't change it. Remember, you can always add to your API, but you can't remove without breaking client code. -keep performance in mind, but don't sacrifice readability for it. -keep classes as immutable as possible. Even if you can't make a class completely immutable, make it as immutable as you can. -only inherit when is-a relationship exists. -if a class is meant to be inherited from, document it -if a class is not meant to be inherited from, prohibit it (some languages let you enforce this, in others, you can just write something like "Do not inherit" in the documentation) (the reason for this is that inheritance violates encapsulation/information hiding) -don't make your client do anything you can do for them (this reduces the amount of boilerplate code your client will have) -don't violate principle of least astonishment (clients on your platform are used to certain behavior in certain situations, go along with this!) -fail fast (i.e. if an incorrect input is sent to your function, stop and display error immediately (best is at compile time, but sometimes you have to do it at runtime)) *Here is a summary of the above summary :)* -extract true requirements into a small (~1 page) specification iteratively -name/document each and every single one of your classes/functions properly (which naturally tends to make them small/cohesive) -don't violate principle of least astonishment (use style/convention/idioms/patterns/behavior present in your clients platform) -don't violate encapsulation/information hiding (don't do inheritance unless its truly an is-a relationship, keep classes/functions as private as possible, etc...) -keep performance in mind, but don't sacrifice readability for it -keep classes as immutable as possible -fail fast -you can always add, but you can't remove (w/o breaking client code) Hope that was useful to someone :) Excellent presenter/presentation. I learned/reinforced a ton. Was also very fun to watch. Thank you very much for sharing this talk.

[@Abdullah-mg5zl]

Thank you! That is an excellent addition. I'm generally pretty good about failing fast but I will admit to not being very good at failing gracefully, definitely need to get into that habit. Thanks again!

[@michor10]

You're the real MVP!

[@lonelym13]

Abdullah Aghazadah I was thirty minutes in. Thank you for the summary. It was a good refresher.

[@sk8sbest]

Can u make a summary of the summary of the summary???

[@Mimsyborogove923]

This video needs to be saved forever. One of the clearest explanations I've heard of best practices for API design/all code you write. He does an incredible job of explaining all the fundamentals, as well as WHY they are fundamental.

[@ChrisAthanas]

Full room and still we live with mountains of messes Maybe ai will help tame the madness

[@TheChodex]

It's really amazing how 12 years later, this talk is still relevant as if it came out yesterday!

[@joedalton9]

I just love these enthusiastic speakers, with loads of experience, and a good sense of humour ... ! Excellent.

[@gtyron]

Looking back today, in the past 2 years, this has vastly impacted the way I write software.

[@JRueStitch]

I love his energy and focus! No wonder he's described so grandly in the intro. :)

[@arthurmee]

Great presentation. I always enjoy listening to Joshua Bloch speaking . . .

[@nampham07]

This talk is invaluable!

[@jjmontesl]

Awesome speaker, so dedicated. I'd love to have the opportunity to chat with someone like this guy some day. Kudos to him.

[@jeetusaikia]

what a presentation it was.... awesome !!

[@vitalya2412]

I am amazed. Thank you for the great talk.

[@hjg7968]

Now March 30,2022. This talk is gold!

[@ReneMaya]

Slides can be found at www.cs.bc.edu/~muller/teaching/cs102/s06/lib/pdf/api-design although you might need to add the PDF extension to the downloaded file

[@victorklimov5254]

Thanks, man!

[@chatsociety]

Great ideas on API design.

[@nand3kudasai]

I wish Google itself attended this before making Android API.

[@fernandosicos]

ouch

[@ChrisAthanas]

Completely ignore their own advice

[@FadkinsDiet]

​@@ChrisAthanasthis is a guest speaker from sun

[@RyanJohnson]

I love this talk :).

[@superjosereborn2]

Excellent concepts. Was looking for a way to improve my coding skills and this nailed it. These are not simple techniques that fade away in a couple of months or years. These are concepts that prevail through time (Watched it @ 2014). Excellent! I've always named variables, functions, classes, methods, and everything else with such squeaky words.

[@sexyplexie]

***** audio appears desynced, can we get this corrected? otherwise this is one of the BEST talks ever given, and it transcends languages, platforms, tools, etc. THANK YOU FOR THE UPLOAD

[@MatsBohlinsson]

I fixed the audio here: kzbin.info/www/bejne/eJvCXpWGZ9yKodk

[@ProgramMax]

Great talk. I'm so glad you mentioned the importance of naming. In fact it shows up twice. Just the other day I was asking programming friends for help with naming. I wanted to check for a win on the diagonals of a tic-tac-toe board. And I wanted a name better than "IsTopLeftBottomRightDiagonalAWin." :D Often when I ask for naming help I'm met with "Just use that name and move on." After hearing that enough I began questioning if I was wasting my time. It's good to hear that naming IS coding.

[@richardcorsale]

I'm going to say this, from 22:00 - 26:00 is without a doubt, the best advice I've ever received regarding API design. It goes something like this: "When in doubt, leave it out"... and yes that applies to you :)

[@DanRossiter]

Great talk! It would be nice if a higher res could be used though. It's extremely difficult to read some of the code used.

[@mannefagerlind7572]

Very good talk. Every junior programmer should listen to and read Josh Bloch.

[@AlexanderSuraphel]

+Manne Fagerlind Is this talk still relevant in 2016?

[@mannefagerlind7572]

+Alexander Suraphel Oh, yes! As long as we're designing APIs we will need to think about best practices. Most of the talk is about developing "binary" APIs using OOP, but some of it is definitely relevant to functional programming and designing REST APIs too, not least the "When in doubt, leave it out!" principle.

[@AlexanderSuraphel]

+Manne Fagerlind +1

[@berlinbrown03]

Great talk

[@ChrisAthanas]

46:54 reading code rendered at 9pt font size with 240dpi resolution is somewhat less than optimal

[@alexdevcamp]

This is definitely in the top 5 coding talks of all time imho

[@madnorbi]

Post the other 4 :)

[@ElijahLynn]

Is there a higher quality version of this out there? This is only 240p and I suspect even in 2007 the source footage was higher than that. I would like to show this at our weekly developers lunch at my company.

[@FerOtero]

480 here: kzbin.info/www/bejne/npbLZYKbd550Y8U

[@momerath42]

@hecatombe youtube wont let me post even a mildly obfuscated URL. The slides are up on examville under the title of the talk.

[@gadeichhorn]

pure gold

[@CVertex]

I agree that naming is ultra important! but sometimes naming things stalls writing code. I find naming some functions super hard, so i rank accuracy with more words over being concise. If you can refactor, then you can come back and rename things to make sense later with more time.

[@JonathanRoberts66]

@jjmontesl Josh is even better in person. His sense of programming aesthetics is strong and they inform his entire being. Even his daily speech is type-safe and semantically precise; he often corrects himself to achieve these goals. He hired me into my first programming job at Transarc in 1990. Working with him was like going to graduate school for CS. To top it all off, Josh is friendly, interesting, funny and of excellent character. It is good to hear that he still quotes Jon Bentley.

[@dieklaue1]

@hecatombe Just google for the name of the talk (can't put the link here somehow).

[@SyntaxColoring]

I'm not so sure about that. I agree that protected is often underused, but I wouldn't say that private members are inherently bad. They're good to use, for example, when the public methods of a superclass are engineered to safely manipulate the object's internal state to maintain some invariant. You don't want that internal state to just be protected, because then subclasses can circumvent the carefully-designed public methods and mess it up by accessing it directly without any checks.

[@flowewritharoma]

pretty great!

[@darkandgreen3212]

why there isnt a better quality video available?

[@olujamesuk]

very good.

[@arisaonwuka1188]

You're into programming?

[@shibinkidd]

@GoogleTechTalks is there an online copy of the papers he distributed in the end? I would like to get one :)

[@Abdullah-mg5zl]

I would also like a copy, were you able to find it? :)

[@aJamesReber]

I searched and found this on ACM; it seems to have the same information that he handed out: dl.acm.org/citation.cfm?id=1176622

[@InXLsisDeo]

You are wrong. The compiler CAN and should help find type errors. In fact, it's one of its most important roles and languages like ML or Haskell enforce strong typing. Things like casting are not allowed. Now Java is not a strongly typed statically typed language, so the ability of the compiler to catch errors is limited. Still, generics have improved things in that regard.

[@ovidiubuligan]

yes indeed

[@djmips]

replace 'hard to misuse' with 'hard to get wrong' to prevent tripping over the word 'use'. ;-)

[@bushiiko]

If only google had attented this meeting before Angular...

[@InXLsisDeo]

Transcription errors: 00:23:17 club --> CORBA 00:28:40 sequel exceptions --> SQL exceptions 00:35:25 [INDISTINCT] --> Joda Time 00:58:45 no pointer exception --> NullPointerException

[@sandrol76]

Joshua rules!

[@fredriley1]

I searched for the talk title, as a whole string, and got a link at lcsd05.cs.tamu.edu/slides/keynote.pdf which seems to have all the slides. An hour is a bit long to sit through at work, even when the speaker knows his onions like this guy.

[@BrendanMetcalfe]

A classic

[@allyourcode]

This was posted in January 2007. Back then, we had to record video with stone and chisel.

[@2011sandeepraj]

At 43:40, An example would have been so much bettter . Speaker using hands to explain such an important point didnt really communicate it very well!

[@Seodotcom]

I guess I need to read the book..

[@AmazeWebs]

I wonder how many times he mentions the word 'API'?

[@koshairulta]

@hecatombe google search for "How To Design A Good API and Why it Matters " from @stanek

[@zedisdeadz]

I think sound is out of sync :/

[@ericcartmansh]

Not found.

[@stanek]

@hecatombe Do a google search for "How To Design A Good API and Why it Matters " The first hit for me is a link to the .pdf I also see your comment is 3 years old ...

[@Mr4thdimention]

This is a mixed bag of good and bad ideas, couldn't keep going after "When in doubt leave it out". It is so not as simple as what he is pitching it to be.

[@c0ntag10n]

240p??

[@antonybooth3293]

+c0ntag10n Yes. Many of the code examples were unreadable, because a smaller window made them too small to read and a full screen was just pixelated. I suspect the 240p was to accomodate a 1 hour video

[@gordonfreemanq]

The video is 10 years old... I don't even think KZbin HD existed at that time.

[@doug65536]

OMGVMCID stands for Oh My God Virtual Machine Cubic Inches of Displacement.

[@antonybooth3293]

+doug65536 I thought it was: Virtual Machine Class ID. How does a Virtual Machine displace anything?

[@greywolf424]

application programming interface

[@Lilinye]

Sure ML, Haskell(and others like Scala) are much better at handling types but this is Java we are talking about... Anyone who says Java's type system is good(for any rational definition of good) is deluding themselves. I have seen it way too often, "programmers" using the compiler to test their code. BTW, dynamically typed languages often disallow for casting as well.

[@ThuyNguyen-bu9ge]

Given how much money Google has, why didn't they produce a better quality video? A good talk is hidden behind all the blurriness.

[@antonybooth3293]

+待化的冰 They were trialing the Google Potato!

[@TheSSton]

at lcsd05.cs.tamu.edu/slides/keynote.pdf or google

[@KrishnaReddySedam]

hi

[@jj9955555]

Higher resolution: kzbin.info/www/bejne/npbLZYKbd550Y8U I can actually read the slides in above link

[@mailgauravjoshi]

There's a dog listening to Joshua as well. See at 45:25 :)

[@rameshemv]

Gaurav Joshi True..Google (self) admittedly is a Canine loving company...no wonder you will find them in their campuses

[@Lilinye]

An amusing part is when he rightly talks about avoiding boilerplate and abusing patterns yet at the end he does exactly that by talking about adding Builders and Factories which are nothing more then unnecessary boilerplate. Java is one of the few languages that needs this kind of boilerplate to be usable Mr. Bloch is intelligent and highly capable, it isnt my intention to say otherwise. It is proof that Java is harmful to ones thinking. He has been twisted and lives in such a rigid box, sad

[@evianelpeehs]

just search for "How To Design A Good API and Why it Matters PDF"

[@daniele1988]

Slides here fwdinnovations.net/whitepaper/APIDesign.pdf

[@minhtruong017]

Isn't this just a subset of Solid Principle?

[@antonybooth3293]

+Minh K. Truong It had very little to do with api design specifically. In most examples, it was just good programming, such as if a class acts on 2 strings, ensure the entry methods require strings instead of objects or something else, or if a method is supposed to return a collection, don't return a null. Elementary stuff really. It surprises me that any Google developers would need a lecture on most of this subject and the rest could be a 1 paragraph memo.

[@minhtruong017]

I dont think is elementary stuff. It is very powerful and useful stuff to keep in mind when coding. Because the most fundamental stuff if build correctly it will lead to stronger foundation and simply future enhancement. Also, i think you missed the mark on what he try to say on passing parameters or your explanation is not clear because If i have an object with 19 properties and the methods need 8 properties of that object.. do you pass the object (not good because passing extra data the method do not required and will confuse future reader), demand for 8 properties (will be hard to maintain if the future we want to add or remove parameters)? what will you do?

[@antonybooth3293]

+Minh K. Truong Really, because I think principles like passing the correct object types to methods and returning what is expected, is elementary. Also, he explained the principle of creating a model to pass as a data contract to a method, if the number of parameters exceeds 3. I personally disagree with this. If there are related properties, such as user credentials, then perhaps these should be passed as a credentials object, but a better principle than wrapping 12 parameters into an object and passing it, would be to red flag your method as being too complex if it requires 12 parameters in the first place. Also, creating a wrapper object, solely for the purpose of passing it to a method is wasteful and potentially error prone, as you're creating more code and a class, just for this one purpose. How is that a good idea? It's much better to follow the single responsibility principle to each method and create separate methods to perform the functionality the one that requires so many parameters is trying to achieve.

[@minhtruong017]

I think passing limited around of parameters is a great idea. I think it should just pass just a parameter object to the method is great. Reasons. 1. Allow coder to abstract the parameter to a more meaningful name. 2. It keep the method simple (usage of the method). 3. It more maintainable. In regards to making single responsibility even at high abstract level you depend on multiple properties to break it into smaller simplify methods to perform the task.

[@antonybooth3293]

+Minh K. Truong So you think replacing a method signature with a custom object is better? Here's a few problems with that: - 1) More code for nothing. You've created a class whose sole purpose is to pass it to a method. What now, 1 class for every method with 2 or more parameters? 2) Overloading. Are you going to create separate classes for each overloaded method, or are you now going to implement conditional business rules in the 1 method, depending on the contents of the class? How easy will it be for a developer to consume that method, to know what properties to populate and when? 3) Stability. You alter the model class to pass additional parameters to the method and your code works and breaks everyone else's that instantiated that class, but didn't populate the new properties. If you needed those new parameters, the correct process would be to overload the method and add the new functionality those parameters offer, to it. So what are you going to do, create another class instead, because you can't overload a method with the same signature? A method is a function that contains everything required to make it work. It has the inbound properties guaranteed by being a part of the signature and the logic within it to return the required object back to the caller. What you are suggesting means the call parameters may never exist, if the model changes. Usages of the method are now likely to break because of the changing of the structure of an object. This is true with any call to a method that passes an object, but because all the parameters are objects instead of a some of them being simple types, it is more likely. You can leave a method alone that works and performs the required function, because the method parameters aren't related, but when you tie them all together into the same object, changing that object could create compile and run time errors through an entire system or dependent systems. 4) Readability. The method signature shows what needs to be passed, what are defaults and what are optional. How is this achieved by instantiating a method object, multiple constructors or factory methods in your model class to determine what parameters are to be populated when instantiated? It's a lot more work that has to be done in the model class and for what, just so you don't have to declare the call parameters with more than 1 object? 5) Bad Practices. By only having 1 parameter, it makes your method call look clean, but the reality is, you could have used the object to wrap dozens of parameters that have to be populated in the calling method instead, so you've just moved the populating of those parameters outside of the method call, before calling the method. Also, if your method requires dozens of parameters, it is going to be doing far more work than 1 method should be. It's functionality should be broken down into separate functional responsibilities and the net result is the methods you create will each require only a few parameters from the collection and negate the need for a custom object in the first place. And then what have you achieved after all this? You've abstracted the method signature, to a collection of properties in a class, solely for the purpose of passing them back to the method, so instead of instantiating an object and assigning the properties, why not just call the method and pass the properties? Wrapping method parameters this way is simply hiding bad code, by creating more bad code.

[@transfire]

It is not bad at all! That's a widespread and terrible misconception. Being able to modify code is the very crux of code reusablitly. Being able to sublcass and modify makes it possible to create functional variations. Private members destroy that possibility. The Question of broken dependency is a separate issue, and should be addressed via versioning, not private members.

[@bluejanis5317]

Cant google afford a good camera?

[@Ephrones]

This video is over 10 years old.

[@bluejanis5317]

Are you saying they couldn't afford it 10 years ago? I dont think so. Even 10 years ago Google was already a huge company!

[@Ephrones]

But YT was 2 years old and had kinda strict file size limits.

[@bluejanis5317]

I guess you win. You know more about that than I do..

[@Ephrones]

It’s not about winning. :) I’m glad I could answer the question.

[@haridaniel777]

FUCKING AUDIO LAG!

[@transfire]

DO NOT make all your Java members private! That is idiotic. In fact private members is the biggest mistake of all time!!! It totally destorys code reusability. Instead of private make them protected. This way subclasses can still access them, but they aren't public API either.

[@Lilinye]

Pretty good presentation. Too bad someone this good actually believes that the compiler should be used to debug code, including type issues. It really brings his credibility into question. It is impossible to use a compiler, especially the Java compiler to root out all type-errors. He completely ignores the role of unit-tests to cover everything that the compiler misses. If the compiler is part of your testing tools, or worse, your only testing tool, it is time to find a new profession.

[@reporterkris]

this might be a 10 year old comment, but i don't quite agree on your statement. I like how you compliment his "good presentation" but go on ranting about topics which he did not even focus on and then personally attacking him Did you even watch his presentation? It was not about unit testing or verifying correctness. It was about designing api's. That has nothing to do with the points you are making. Go look at languages like F# and its type system, and you will get an idea of how powerful tool it can be. - If you can avoid bugs at compile-level, you will save time and headache, and you would have to write less tests if you had fully statically typed code. "Stringly typed" systems makes it very easy to make human mistakes. - His credibility is probably far above what your "level" will ever be ​ -This was not a talk about unit testing or verifying correctness. It was about designing apis. - He never said that making a statically typed api would remove all bugs. - It's not the compiler that "misses" the bugs, it is the programmer

[@isbestlizard]

Big pig apis... oh my god, Win32... every damn method has 10 to 20 parameters taking security descriptors and handles to fuck knows what else... sometimes null is fine othertimes null is BAD. ugggh I hate it so much