What do you think?
Rate this book
Practical API Design: Confessions of a Java Framework Architect
You might think more than enough design books exist in the programming world already. In fact, there are so many that it makes sense to ask why you would read yet another. Is there really a need for yet another design book? In fact, there is a greater need than ever before, and Practical API Confessions of a Java Framework Architect fills that need!
414 pages, Hardcover
First published January 1, 2008
143 people want to read
Ratings & Reviews
Friends & Following
Create a free account to discover what your friends think of this book!
Community Reviews
Displaying 1 - 13 of 13 reviews
April 11, 2021
On the one hand, this books contains worthwhile discussions and tips on how to design APIs that can evolve while maintaining backward compatibility, with a case study, code examples from an "API Design Fest" the author organized, and using official Java and NetBeans APIs as examples of good and bad designs. One gets the sense that the author clearly has experience, and took the time to think about the mistakes he made and saw made during several years, in the search of ways to detect and prevent them.
On the other hand, the amount of side comments, digressions and repetition that it contains hurt more than they help. I think the author could have packed all the useful information in about half the book.
On the other hand, the amount of side comments, digressions and repetition that it contains hurt more than they help. I think the author could have packed all the useful information in about half the book.
June 30, 2017
Probably, my expectations were too high from the book title. A lot of recommendations indeed makes sense, but all of them are mostly around Java and library/IDEA framework applications. I wished the author touched more of the server side - but looking at writer background it is just not possible.
May 21, 2022
Despite this book has been written in 2008 it still has some value in 2022 when I'm reading it.
Note that the API here is not the "Web API (REST/GraphQL") that is usually understood by this term. But some ideas can be also applied to the Web API.
The API here are the classes and interfaces that you create and the book teaches you to create them in a way that can be safely used and extended. So this book is mostly useful for creators of Java librarie or frameworks.
The main point of the first part of the book is to explain that a published API needs to be supported forever and so publishing an API in an important step. It also recommends not to expose more than you want.
It makes an important separation of API and SPI (Service Provider Interface). SPI meant to be extended, API is meant to be mostly used as is without or with minimal extending . An example of a modern SPI is JDBC - to add a support for a new Db driver you need to extend or implement certain classes. An example of a modern API is Apache Commons Library - normally you just use it without extending. Spring framework is also an API because the developer mostly uses the existing Spring annotations instead of subclassing. An important note: It's very bad to mix SPI and API in a single class, because you cannot change after that. Changing it would violate either an API or an SPI contract.
A big part of the book concerns method visibility as well as declaring classes and methods final. General idea - declare classes as final unless you explicitly allow them to be extended. Same about protected abstract methods - they tell the developer "override and implement me".
Chapter 10 contains a very good table "The meaning of Java Access modifiers When Designing an API", which summarizes all the ideas in one place (you can google this table by the exact sentence) and an important idea: if possible when writing non-private methods try to use only public final, protected abstract and protected final methods as they have single meanings.
Chapter 17 contain an interesting example of an API training called "API Design Fest".
Participants get a description of an toy API: write classes that can support a simple mathematical expression with integers and support the "plus" operation. Then they are asked to write tests, then they are asked to implement the "minus" operation and finally they are asked to implement v.2 of API that supports real numbers and keep the backwards compatibility with integers (meaning all old tests must compile and work).
Finally it mentions long-term API support or API rewrite especially when there is not much documentation on it. In this case you should realize that "The old behavior is the specification" and your goal is to mimic that behavior.
Note that the API here is not the "Web API (REST/GraphQL") that is usually understood by this term. But some ideas can be also applied to the Web API.
The API here are the classes and interfaces that you create and the book teaches you to create them in a way that can be safely used and extended. So this book is mostly useful for creators of Java librarie or frameworks.
The main point of the first part of the book is to explain that a published API needs to be supported forever and so publishing an API in an important step. It also recommends not to expose more than you want.
It makes an important separation of API and SPI (Service Provider Interface). SPI meant to be extended, API is meant to be mostly used as is without or with minimal extending . An example of a modern SPI is JDBC - to add a support for a new Db driver you need to extend or implement certain classes. An example of a modern API is Apache Commons Library - normally you just use it without extending. Spring framework is also an API because the developer mostly uses the existing Spring annotations instead of subclassing. An important note: It's very bad to mix SPI and API in a single class, because you cannot change after that. Changing it would violate either an API or an SPI contract.
A big part of the book concerns method visibility as well as declaring classes and methods final. General idea - declare classes as final unless you explicitly allow them to be extended. Same about protected abstract methods - they tell the developer "override and implement me".
Chapter 10 contains a very good table "The meaning of Java Access modifiers When Designing an API", which summarizes all the ideas in one place (you can google this table by the exact sentence) and an important idea: if possible when writing non-private methods try to use only public final, protected abstract and protected final methods as they have single meanings.
Chapter 17 contain an interesting example of an API training called "API Design Fest".
Participants get a description of an toy API: write classes that can support a simple mathematical expression with integers and support the "plus" operation. Then they are asked to write tests, then they are asked to implement the "minus" operation and finally they are asked to implement v.2 of API that supports real numbers and keep the backwards compatibility with integers (meaning all old tests must compile and work).
Finally it mentions long-term API support or API rewrite especially when there is not much documentation on it. In this case you should realize that "The old behavior is the specification" and your goal is to mimic that behavior.
November 19, 2012
Fantastic read for advanced level programmers with a good core understanding of fundamentals. Reads like advice from an experienced colleague and feels rational rather than preachy. Could be improved by demonstrating the theory in other languages, but perhaps that's better left for another author to explore
August 9, 2019
Very useful. Using Java 5, so a revamp could be handy (Java 8 default methods, Java 9 modules), but the most stuff is still applicable. Moreover there is some newer tooling than Ant. Interesting philosophical digressions.
December 3, 2009
A new way of designing application, in line with latest trends (open source, component design...)
September 25, 2010
Awesome book if you wanna know what API design is all about
April 13, 2012
Nice book if you are building *any* API
December 18, 2012
Great reference on API design
October 5, 2015
some basic tips, a little longbreathed
May 21, 2017
The topic is painfully in demand. The contents and observations are humble.
Read
July 15, 2017Api design confession of a java developer
-Cluelessness is positiv, one canot understand everything because the brain is finit, but being able to manuver shallowly is as important as deep knowlege of things.
-Avoid setters as much as possible when designing api
-Object oriented languages ezpress how nature works, by having a mamal class and have cat and dog classes subclassing mamal class, this is whyobject oriented languages are so good at explaining real world
-Dont expose deep hirarchies. In essense subclassing is just a switch statement, ==once this statment gets to complex its hard for the user to use it.==
-If the subclassing is deeper than two levels. Stop and ask yourself if its just for subclass reuse. Keep in mind the readability of the api. And the inplace issue. See p. 115 in api design
-If you want to be carefull you should never add a method to a subclassable api class
-In api classes Never add methods to classes others can implement
-strive for selectiv cluelessness, and selectiv deep knowlege
Locality of packages should be organized in a way that the most used classed are easy to find and packages that are less used should be tucked away somewhere 89/20 rule applies
You can improve your planing skils if tests are written early.
The more you expose of your apy the less flexible and harder to evolve it becomes.
To prevwnt inherentance confusion make use of final functions in superclasses.
Rewrite methods with many meanings into methods with clear meanings: An abstract protected function clearly communicatrs to the user that it should be overriden. A public / protected final function clearly communicates that it should be called not pveridden. Api design is about communication. The problem with methpds that can be overidden and called from the subclass is that they can easily br misued. Add table from screenshots here
Functional programming will come, its easy to cose for multicore processors, its beaitifull and geometric, but the learning curve is steep and is bot thought in schools and its unknown when its time is due. Haskell is such a language
Apply imutabilty whenever possible avoid setters as much as possible, the more static the api code is the more cluøess the user can be.
Api should be ballenced between: Simplicity, robustness, correctness, evolution readiness
Even the slightest difference in initial factors, can lead to completly different sets of suggestions on how best solving problems. Think of the universe as an analogy, all laws of physics could have been totaly different if the universe inital factors were different during the start of the big bang.
An api that is naturally easy to use, is better than an api that has many ways to be misused.
Ease of use is more important than correctness, think about array = thefilestream.read() annology.
When designing an api you should make simple things easy, while making complex things possible. Dont scare away newcommers,
In striving towards a simple api, dont treat your users as ideots
Hide complex functionality, in different sub packages than sipmle functionality class are located
Module version dependensy: To maintainbackward compatebility you can introduce switchbased divoded functionality accprding to what version is passed in witht the cobstructor argumebt. If version 1 do this if version 2 do this.
Good api documentation is the facade that can shield the user from internal complexity and thus integrate cluelessness into their programing
The less is more design approche: use factory classes to not expose constructors, Provide classes that dont subclass. This is the defencive approch
Pro Its nice to explore other "good" developers thoughts
Cons This guy could benifit from building other apis than just netbeans, its evident that is base of knowlefe is rich but not very broad. He makes recomendations that are not very universally applicable. Way to long and repetative. Hard to plow through.
-Cluelessness is positiv, one canot understand everything because the brain is finit, but being able to manuver shallowly is as important as deep knowlege of things.
-Avoid setters as much as possible when designing api
-Object oriented languages ezpress how nature works, by having a mamal class and have cat and dog classes subclassing mamal class, this is whyobject oriented languages are so good at explaining real world
-Dont expose deep hirarchies. In essense subclassing is just a switch statement, ==once this statment gets to complex its hard for the user to use it.==
-If the subclassing is deeper than two levels. Stop and ask yourself if its just for subclass reuse. Keep in mind the readability of the api. And the inplace issue. See p. 115 in api design
-If you want to be carefull you should never add a method to a subclassable api class
-In api classes Never add methods to classes others can implement
-strive for selectiv cluelessness, and selectiv deep knowlege
Locality of packages should be organized in a way that the most used classed are easy to find and packages that are less used should be tucked away somewhere 89/20 rule applies
You can improve your planing skils if tests are written early.
The more you expose of your apy the less flexible and harder to evolve it becomes.
To prevwnt inherentance confusion make use of final functions in superclasses.
Rewrite methods with many meanings into methods with clear meanings: An abstract protected function clearly communicatrs to the user that it should be overriden. A public / protected final function clearly communicates that it should be called not pveridden. Api design is about communication. The problem with methpds that can be overidden and called from the subclass is that they can easily br misued. Add table from screenshots here
Functional programming will come, its easy to cose for multicore processors, its beaitifull and geometric, but the learning curve is steep and is bot thought in schools and its unknown when its time is due. Haskell is such a language
Apply imutabilty whenever possible avoid setters as much as possible, the more static the api code is the more cluøess the user can be.
Api should be ballenced between: Simplicity, robustness, correctness, evolution readiness
Even the slightest difference in initial factors, can lead to completly different sets of suggestions on how best solving problems. Think of the universe as an analogy, all laws of physics could have been totaly different if the universe inital factors were different during the start of the big bang.
An api that is naturally easy to use, is better than an api that has many ways to be misused.
Ease of use is more important than correctness, think about array = thefilestream.read() annology.
When designing an api you should make simple things easy, while making complex things possible. Dont scare away newcommers,
In striving towards a simple api, dont treat your users as ideots
Hide complex functionality, in different sub packages than sipmle functionality class are located
Module version dependensy: To maintainbackward compatebility you can introduce switchbased divoded functionality accprding to what version is passed in witht the cobstructor argumebt. If version 1 do this if version 2 do this.
Good api documentation is the facade that can shield the user from internal complexity and thus integrate cluelessness into their programing
The less is more design approche: use factory classes to not expose constructors, Provide classes that dont subclass. This is the defencive approch
Pro Its nice to explore other "good" developers thoughts
Cons This guy could benifit from building other apis than just netbeans, its evident that is base of knowlefe is rich but not very broad. He makes recomendations that are not very universally applicable. Way to long and repetative. Hard to plow through.
Currently reading
May 9, 2019I have soft copy of this book for a long time but have no chance to read it. Recently, i am confused on how to design an good API, so it comes back into my eyes. What a coincidence that this book also recommended by other gurus in China. Therefore i think it is time to give it my focus right now.
Displaying 1 - 13 of 13 reviews