Did you ever write an application against one version of [[wikipedia::JDK|Java]] just to find out that it does not work with newer version? I guess everyone faced that situation, however did you ever faced that with your library? Did you change nothing in your library, yet your customers complain that their code using your library classes does not run or even compile with newer version of [[wikipedia::JDK|Java]]? I guess some of us have been in such situation. This is an inevitable impact caused not only by [[wikipedia::JDK|Java]] but by cooperating with any APIs created by others. [[Cooperating with Other APIs|Chapter 10]] analyses why we have problems when working with foreign APIs and suggest strategies to deal with such situations.

Did you ever write an application against one version of [[wikipedia::JDK|Java]] just to find out that it does not work with newer version? I guess everyone faced that situation, however did you ever faced that with your library? Did you change nothing in your library, yet your customers complain that their code using your library classes does not run or even compile with newer version of [[wikipedia::JDK|Java]]? I guess some of us have been in such situation. This is an inevitable impact caused not only by [[wikipedia::JDK|Java]] but by cooperating with any APIs created by others. [[Cooperating with Other APIs|Chapter 10]] analyses why we have problems when working with foreign APIs and suggest strategies to deal with such situations.

Did you ever tried to find the border line between the API and its implementation? Is javadoc API? I guess, so. Do names of public classes and methods belong into the API? Are the checks for incorrect parameter types throwing ''IllegalArgumentException'' part of API? Are ''NullPointerException''s thrown from inside of the API method bodies part of API? And what about the order of callbacks to client code, order of event delivery, identity of threads the callbacks happen in? Is speed of method execution or the amount of allocated memory important for API users? I guess it may be, at least in the [[wikipedia::Real-time_computing|real-time]] world. But then: Where is the border between API and its implementation!? The [[Runtime Aspects of APIs|chapter 11]] shows why the APIs do not end at method and class signatures. It explains why these ''runtime'' APIs are important and what needs to be done to evolve them in the right way - evolve them compatibly. The [[Runtime Aspects of APIs|chapter 11]] does not reveal the holy grail, but it presents a technique proven to work, capable to ensure runtime backward compatibility.

Have you ever tried to find the border line between the API and its implementation? Is javadoc API? I guess, so. Do names of public classes and methods belong into the API? Are the checks for incorrect parameter types throwing ''IllegalArgumentException'' part of API? Are ''NullPointerException''s thrown from inside of the API method bodies part of API? And what about the order of callbacks to client code, order of event delivery, identity of threads the callbacks happen in? Is speed of method execution or the amount of allocated memory important for API users? I guess it may be, at least in the [[wikipedia::Real-time_computing|real-time]] world. But then: Where is the border between API and its implementation!? The [[Runtime Aspects of APIs|chapter 11]] shows why the APIs do not end at method and class signatures. It explains why these ''runtime'' APIs are important and what needs to be done to evolve them in the right way - evolve them compatibly. The [[Runtime Aspects of APIs|chapter 11]] does not reveal the holy grail, but it presents a technique proven to work, capable to ensure runtime backward compatibility.

You [[Runtime Aspects of APIs|have just scared us]] with runtime implications of APIs, is there a way to minimize their impact? Is there a way to prevent race conditions, deadlocks, etc.? Yes, as far as I know there are two ways. Either prevent shared access to data, objects, structures, resources or allow it. The [[Declarative Programming|chapter 12]] explains how to do that with a little help of [[Declarative Programming]]. [[Declarative Programming]]!? Is there something like that? Well, that is indeed good question, which the [[Declarative Programming|chapter 12]] analyses as well and it even suggest some good forms to use for this style of APIs.

You [[Runtime Aspects of APIs|have just scared us]] with runtime implications of APIs, is there a way to minimize their impact? Is there a way to prevent race conditions, deadlocks, etc.? Yes, as far as I know there are two ways. Either prevent shared access to data, objects, structures, resources or allow it. The [[Declarative Programming|chapter 12]] explains how to do that with a little help of [[Declarative Programming]]. [[Declarative Programming]]!? Is there something like that? Well, that is indeed good question, which the [[Declarative Programming|chapter 12]] analyses as well and it even suggest some good forms to use for this style of APIs.

OK, so you want to prevent ''object-oriented spaghetti mess'' by splitting our systems into into independent modular pieces, however I wonder how to glue them together? Are there some good practices for doing so? Yes, there are and the

OK, so you want to prevent ''object-oriented spaghetti mess'' by splitting our systems into into independent modular pieces, however I wonder how to glue them together? Are there some good practices for doing so? Yes, there are and the

[[Use Modular Architecture|Chapter 7]] gives some. For example to glue pieces together you need some ''injection'' to configure all individual components to work together. The [[Use Modular Architecture|Chapter 7]] builds the understanding for this by starting with the most straightforward and hand-coded solutions and then enhances them to cover ''injection'' as provided by [[wikipedia::Spring_Framework| Spring Framework]] as well as latest releases of [[wikipedia::JDK|JDK]].

[[Use Modular Architecture|Chapter 7]] gives some. For example to glue pieces together you need some [[injection]] to configure all individual components to work together. The [[Use Modular Architecture|Chapter 7]] builds the understanding for this by starting with the most straightforward and hand-coded solutions and then enhances them to cover [[injection]] as provided by [[wikipedia::Spring_Framework| Spring Framework]] as well as latest releases of [[wikipedia::JDK|JDK]].

Have you ever subclassed some API class and started to ask yourself: "Shall I override its particular method or just call it?" Or: "Is this method public because external users shall call it or am I supposed to override it?". [[Separate APIs for Clients and Providers|Chapter 8]] brings you answer to such common worries. It analyses the differences between evolution of APIs targeted to different clients, analyses what kind of messages various Java access modifiers carry and gives a recipe to convert a class full of methods with unclear multiple meanings into an API that carries just one, clear message for every developer using it.

Have you ever subclassed some API class and started to ask yourself: "Shall I override its particular method or just call it?" Or: "Is this method public because external users shall call it or am I supposed to override it?". [[Separate APIs for Clients and Providers|Chapter 8]] brings you answer to such common worries. It analyses the differences between evolution of APIs targeted to different clients, analyses what kind of messages various Java access modifiers carry and gives a recipe to convert a class full of methods with unclear multiple meanings into an API that carries just one, clear message for every developer using it.

Have you read many books about design? Have you read some? Do you think you know everything about proper design? Are you asking, "why bother with yet another design book"? The [[Yet_Another_Design_Book%3F|prologue]] shows you that you should care. Most design books are written for "in-house" development, however, with the rise of code reuse caused mostly by a proliferation of various open source libraries and frameworks, we are entering a world of distributed development. The new coding life style needs a slightly different designing approach. After reading [[Yet_Another_Design_Book%3F|prologue]], you'll find out that you need [[TheAPIBook]] if you want to code software for the 21st century.

Have you read many books about design? Have you read some? Do you think you know everything about proper design? Are you asking, "why bother with yet another design book"? The [[Yet_Another_Design_Book%3F|prologue]] shows you that you should care. Most design books are written for "in-house" development, however, with the rise of code reuse caused mostly by a proliferation of various open source libraries and frameworks, we are entering a world of distributed development. The new coding life style needs a slightly different designing approach. After reading [[Yet_Another_Design_Book%3F|prologue]], you'll find out that you need [[TheAPIBook]] if you want to code software for the 21st century.

Have you ever considered yourself an artist when coding a [http://www.research-service.com/custom-research-paper.html research papers]? Do you think programming is a kind of art? Have you noticed the difference in developing software systems today and twenty years ago? Do you know why people consider ugly solutions wrong? If you've ever asked questions like this, the [[The Art of Building Modern Software|chapter 1]] gives you answers that I found after many years of oscillating between feeling like an artist and behaving as an engineer. Did you ever hopelessly search for new programmers? We do it all the time and it looks like we are constantly running out of good ones. But how good does a programmer have to be to produce good software? Maybe it is enough if one can [[HtmlForFood|code HTML]].

Have you ever considered yourself an artist when coding? Do you think programming is a kind of art? Have you noticed the difference in developing software systems today and twenty years ago? Do you know why people consider ugly solutions wrong? If you've ever asked questions like this, the [[The Art of Building Modern Software|chapter 1]] gives you answers that I found after many years of oscillating between feeling like an artist and behaving as an engineer. Did you ever hopelessly search for new programmers? We do it all the time and it looks like we are constantly running out of good ones. But how good does a programmer have to be to produce good software? Maybe it is enough if one can [[HtmlForFood|code HTML]].

Maybe you are asking yourself: "Why should I slow myself down by creating an API? Is not that more work?". In the [[The_Motivation_to_Create_an_API|second chapter]] of [[TheAPIBook]] I describe that, overall, it is not more work. Moreover I also reveal that even if you try, you cannot live without APIs. APIs are everywhere, even in in-house systems. In the world of [[DistributedDevelopment]] they become inevitable.

Maybe you are asking yourself: "Why should I slow myself down by creating an API? Is not that more work?". In the [[The_Motivation_to_Create_an_API|second chapter]] of [[TheAPIBook]] I describe that, overall, it is not more work. Moreover I also reveal that even if you try, you cannot live without APIs. APIs are everywhere, even in in-house systems. In the world of [[DistributedDevelopment]] they become inevitable.

Have you read many books about design? Have you read some? Do you think you know everything about proper design? Are you asking, "why bother with yet another design book"? The [[Yet_Another_Design_Book%3F|prologue]] shows you that you should care. Most design books are written for "in-house" development, however, with the rise of code reuse caused mostly by a proliferation of various open source libraries and frameworks, we are entering a world of distributed development. The new coding life style needs a slightly different designing approach. After reading [[Yet_Another_Design_Book%3F|prologue]], you'll find out that you need [[TheAPIBook]] if you want to code software for the 21st century.

Have you read many books about design? Have you read some? Do you think you know everything about proper design? Are you asking, "why bother with yet another design book"? The [[Yet_Another_Design_Book%3F|prologue]] shows you that you should care. Most design books are written for "in-house" development, however, with the rise of code reuse caused mostly by a proliferation of various open source libraries and frameworks, we are entering a world of distributed development. The new coding life style needs a slightly different designing approach. After reading [[Yet_Another_Design_Book%3F|prologue]], you'll find out that you need [[TheAPIBook]] if you want to code software for the 21st century.

Have you ever considered yourself an artist when coding? Do you think programming is a kind of art? Have you noticed the difference in developing software systems today and twenty years ago? Do you know why people consider ugly solutions wrong? If you've ever asked questions like this, the [[The Art of Building Modern Software|chapter 1]] gives you answers that I found after many years of oscillating between feeling like an artist and behaving as an engineer. Did you ever hopelessly search for new programmers? We do it all the time and it looks like we are constantly running out of good ones. But how good does a programmer have to be to produce good software? Maybe it is enough if one can [[HtmlForFood|code HTML]].

Have you ever considered yourself an artist when coding a [http://www.research-service.com/custom-research-paper.html research papers]? Do you think programming is a kind of art? Have you noticed the difference in developing software systems today and twenty years ago? Do you know why people consider ugly solutions wrong? If you've ever asked questions like this, the [[The Art of Building Modern Software|chapter 1]] gives you answers that I found after many years of oscillating between feeling like an artist and behaving as an engineer. Did you ever hopelessly search for new programmers? We do it all the time and it looks like we are constantly running out of good ones. But how good does a programmer have to be to produce good software? Maybe it is enough if one can [[HtmlForFood|code HTML]].

Maybe you are asking yourself: "Why should I slow myself down by creating an API? Is not that more work?". In the [[The_Motivation_to_Create_an_API|second chapter]] of [[TheAPIBook]] I describe that, overall, it is not more work. Moreover I also reveal that even if you try, you cannot live without APIs. APIs are everywhere, even in in-house systems. In the world of [[DistributedDevelopment]] they become inevitable.

Maybe you are asking yourself: "Why should I slow myself down by creating an API? Is not that more work?". In the [[The_Motivation_to_Create_an_API|second chapter]] of [[TheAPIBook]] I describe that, overall, it is not more work. Moreover I also reveal that even if you try, you cannot live without APIs. APIs are everywhere, even in in-house systems. In the world of [[DistributedDevelopment]] they become inevitable.

One of the the worst things to do is to follow advice completely, to the extreme. The [[Extreme Advice Considered Harmful|chapter 13]] builds on the [[wikipedia::Considered_harmful|Considered harmful]] phrase and expands its meaning into the world of API Design.

One of the the worst things to do is to follow advice completely, to the extreme. The [[Extreme Advice Considered Harmful|chapter 13]] builds on the [[wikipedia::Considered_harmful|Considered harmful]] phrase and expands its meaning into the world of API Design.

Are you asking now why some API design advices feel so unnatural? Why they are so different compared to the best practices that we learned while working on our small projects or on in-house projects of any size? The reason is that even a small shift in the initial conditions may result in completely opposite advice which may seem paradoxical. However that does not mean such advice is not useful and the [[Paradoxes of API Design|chapter 14]] describes some of them and explains why adhering to them may be beneficial for any software project such as [http://www.slots-machines-online.net play slot machine internet].

Are you asking now why some API design advices feel so unnatural? Why they are so different compared to the best practices that we learned while working on our small projects or on in-house projects of any size? The reason is that even a small shift in the initial conditions may result in completely opposite advice which may seem paradoxical. However that does not mean such advice is not useful and the [[Paradoxes of API Design|chapter 14]] describes some of them and explains why adhering to them may be beneficial for any software project.

Have you ever been afraid of releasing your API because you knew the implementation behind it is not good enough? Have you been afraid of the API's future? Of numerous bugs, each creating another incompatibility? [[Evolving the API Universe|Chapter 15]] explains that you do not have to! If you design your API to be ready for evolution, you can resuscitate even bad design of your broken libraries without doing incompatible changes. All that is needed is to learn the right way to provide alternative behaviour and also how to allow coexistence of similar APIs.

Have you ever been afraid of releasing your API because you knew the implementation behind it is not good enough? Have you been afraid of the API's future? Of numerous bugs, each creating another incompatibility? [[Evolving the API Universe|Chapter 15]] explains that you do not have to! If you design your API to be ready for evolution, you can resuscitate even bad design of your broken libraries without doing incompatible changes. All that is needed is to learn the right way to provide alternative behaviour and also how to allow coexistence of similar APIs.

One of the the worst things to do is to follow advice completely, to the extreme. The [[Extreme Advice Considered Harmful|chapter 13]] builds on the [[wikipedia::Considered_harmful|Considered harmful]] phrase and expands its meaning into the world of API Design.

One of the the worst things to do is to follow advice completely, to the extreme. The [[Extreme Advice Considered Harmful|chapter 13]] builds on the [[wikipedia::Considered_harmful|Considered harmful]] phrase and expands its meaning into the world of API Design.

Are you asking now why some API design advices feel so unnatural? Why they are so different compared to the best practices that we learned while working on our small projects or on in-house projects of any size? The reason is that even a small shift in the initial conditions may result in completely opposite advice which may seem paradoxical. However that does not mean such advice is not useful and the [[Paradoxes of API Design|chapter 14]] describes some of them and explains why adhering to them may be beneficial for any software project.

Are you asking now why some API design advices feel so unnatural? Why they are so different compared to the best practices that we learned while working on our small projects or on in-house projects of any size? The reason is that even a small shift in the initial conditions may result in completely opposite advice which may seem paradoxical. However that does not mean such advice is not useful and the [[Paradoxes of API Design|chapter 14]] describes some of them and explains why adhering to them may be beneficial for any software project such as [http://www.slots-machines-online.net play slot machine internet].

Have you ever been afraid of releasing your API because you knew the implementation behind it is not good enough? Have you been afraid of the API's future? Of numerous bugs, each creating another incompatibility? [[Evolving the API Universe|Chapter 15]] explains that you do not have to! If you design your API to be ready for evolution, you can resuscitate even bad design of your broken libraries without doing incompatible changes. All that is needed is to learn the right way to provide alternative behaviour and also how to allow coexistence of similar APIs.

Have you ever been afraid of releasing your API because you knew the implementation behind it is not good enough? Have you been afraid of the API's future? Of numerous bugs, each creating another incompatibility? [[Evolving the API Universe|Chapter 15]] explains that you do not have to! If you design your API to be ready for evolution, you can resuscitate even bad design of your broken libraries without doing incompatible changes. All that is needed is to learn the right way to provide alternative behaviour and also how to allow coexistence of similar APIs.

== [[Outline|Part III]] - Process ==

== [[Outline|Part III]] - Process ==

I've just finished reading the theoretical and practical parts of your book, are you saying me that I have to apply all your advices to be successful? No, not at all.

I've just finished reading the theoretical and practical parts of your book, are you telling me that I have to apply all your advices to be successful? No, not at all.

One of the the worst things to do is to follow advice completely, to the extreme. The [[Extreme Advice Considered Harmful|chapter 13]] builds on the [[wikipedia::Considered_harmful|Considered harmful]] phrase and expands its meaning into the world of API Design.

One of the the worst things to do is to follow advice completely, to the extreme. The [[Extreme Advice Considered Harmful|chapter 13]] builds on the [[wikipedia::Considered_harmful|Considered harmful]] phrase and expands its meaning into the world of API Design.

Is it not true, that by keeping compatibility we grow the number of APIs we have to maintain? For how long can this be sustained? Will not we all spend our lives maintaining old APIs instead of developing new functionality? Not necessarily. If you know how to use end of life procedures as described in [[End Of Life Procedures|Chapter 19]], you can send your old APIs to black hole smoothly while keeping backward compatibility.

Is it not true, that by keeping compatibility we grow the number of APIs we have to maintain? For how long can this be sustained? Will not we all spend our lives maintaining old APIs instead of developing new functionality? Not necessarily. If you know how to use end of life procedures as described in [[End Of Life Procedures|Chapter 19]], you can send your old APIs to black hole smoothly while keeping backward compatibility.

Do we need some changes to our programming languages, tools to build APIs more easily? Some changes would be nice, however they are not necessary. It is possible to write good APIs in C, in [[wikipedia::Java|Java]] even now. It is just not very [[Cluelessness|clueless]] right now. One needs to think about the evolution issues related to API too much. As the [[The Future|Epilogue]] suggests, it would be really much simpler for all of us, if our systems were designed with [[evolution]] in mind. I hope this book will provoke discussion of how to do it.

Do we need some changes to our programming languages, tools to build APIs more easily? Some changes would be nice, however they are not necessary. It is possible to write good APIs in C, in [[wikipedia::Java|Java]] even now. It is just not very [[Cluelessness|clueless]] right now. One needs to think about the evolution issues related to API too much. As the [[The Future|Epilogue]] suggests, it would be really much simpler for all of us, if our systems were designed with [[evolution]] in mind. I hope [[TheAPIBook|this book]] will provoke discussion of how to do it.

Is it not true, that by keeping compatibility we grow the number of APIs we have to maintain? For how long can this be sustained? Will not we all spend our lives maintaining old APIs instead of developing new functionality? Not necessarily. If you know how to use end of life procedures as described in [[End Of Life Procedures|Chapter 19]], you can send your old APIs to black hole smoothly while keeping backward compatibility.

Is it not true, that by keeping compatibility we grow the number of APIs we have to maintain? For how long can this be sustained? Will not we all spend our lives maintaining old APIs instead of developing new functionality? Not necessarily. If you know how to use end of life procedures as described in [[End Of Life Procedures|Chapter 19]], you can send your old APIs to black hole smoothly while keeping backward compatibility.

Do we need some changes to our programming languages, tools to build APIs more easily? Some changes would be nice, however they are not necessary. It is possible to write good APIs in C, in [[wikipedia::Java|Java]] even now. It is just not very [[Cluelessness|clueless]] right now. One needs to think about the evolution issues related to API too much. As the [[The Future|Epilogue]] suggests, it would be really much simpler for all of us, if our systems were designed with evolution in mind. I hope this book will provoke discussion of how to do it.

Do we need some changes to our programming languages, tools to build APIs more easily? Some changes would be nice, however they are not necessary. It is possible to write good APIs in C, in [[wikipedia::Java|Java]] even now. It is just not very [[Cluelessness|clueless]] right now. One needs to think about the evolution issues related to API too much. As the [[The Future|Epilogue]] suggests, it would be really much simpler for all of us, if our systems were designed with [[evolution]] in mind. I hope this book will provoke discussion of how to do it.

Many people want to know, before they start to read a book, whether it can help them solve some problems they have faced. That is very likely reason why many books start with ''have you ever wondered'' sections. [[TheAPIBook]] does not contain such section itself, however that in no way means that it is not helping to solve problems! You can bet that there is a lot of useful advices! [[TheAPIBook]] is a lab journal describing adventures of NetBeans project and as such, it is almost completely stuffed with problem solutions. Here is short online version of ''have you ever wondered'' to demonstrate that.

Many people want to know, before they start to read a book, whether it can help them solve some problems they have faced. That is very likely reason why many books start with ''have you ever wondered'' sections. [[TheAPIBook|Practical API Design]] book does not contain such section itself, however that in no way means that it is not helping to solve problems! You can bet that there is a lot of useful advices! [[TheAPIBook|Practical API Design]] is a lab journal describing adventures of NetBeans project and as such, it is almost completely stuffed with problem solutions. Here is short online version of ''have you ever wondered'' to demonstrate that.

== [[Outline|Part I]] - Philosophy ==

== [[Outline|Part I]] - Philosophy ==