The API
-+
Sergey Konstantinov. The API.
- yatwirl@gmail.com · linkedin.com/in/twirl · patreon.com/yatwirl
The API-first development is one of the hottest technical topics nowadays, since many companies started to realize that API serves as a multiplicator to their opportunities—but it also amplifies the design mistakes as well.
-This book is dedicated to designing APIs: how to build the architecture properly, from a high-level planning down to final interfaces, and to extend API in a backwards-compatible manner.
-Illustrations & inspiration by Maria Konstantinova · art.mari.ka
+This book is written to share the expertise and describe the best practices in designing and developing APIs. In Section I, we'll discuss the API architecture as a concept: how to build the hierarchy properly, from high-level planning down to final interfaces. Section II is dedicated to expanding existing APIs in a backwards-compatible manner. Finally, in Section III we will talk about the API as a product.
+Illustrations & inspiration by Maria Konstantinova · art.mari.ka
This book is distributed under the Creative Commons Attribution-NonCommercial 4.0 International licence.
-Source code available at github.com/twirl/The-API-Book
-Introduction
Chapter 1. On the Structure of This Book
+Source code available at github.com/twirl/The-API-Book
+Introduction
Chapter 1. On the Structure of This Book
The book you're holding in your hands comprises this Introduction and two sections: ‘The API Design’ and ‘The Backwards Compatibility’.
In Section I, we will discuss designing APIs as a concept: how to build the architecture properly, from high-level planning down to final interfaces.
Section II is dedicated to an API lifecycle: how interfaces evolve over time, and how to elaborate the product to match users' needs.
@@ -348,7 +610,7 @@ h1 {In other words, hundreds or even thousands of different APIs must work correctly to make basic actions possible, like viewing a webpage. Modern internet technologies simply couldn't exist without these tons of APIs working fine.
An API is an obligation. A formal obligation to connect different programmable contexts.
When I'm asked for an example of a well-designed API, I usually show a picture of a Roman aqueduct:
- +
- it interconnects two areas;
- backwards compatibility being broken not a single time in two thousand years. @@ -2842,6 +3104,648 @@ ProgramContext.dispatch = (action) => {
NB. The perfect example of avoiding this anti-pattern is compiler development; usually, the next compiler's version is compiled with the previous compiler's version.
5. Keep a notepad
Whatever tips and tricks that were described in the previous chapters you use, it's often quite probable that you can't do anything to prevent the API inconsistencies start piling up. It's possible to reduce the speed of this stockpiling, foresee some problems, and have some interface durability reserved for future use. But one can't foresee everything. At this stage, many developers tend to make some rash decisions, e.g. releasing a backwards-incompatible minor version to fix some design flaws.
-We highly recommend never doing that. Remember that the API is a multiplier of your mistakes either. What we recommend is to keep a serenity notepad — to fix the lessons learned, and not to forget to apply this knowledge when the major API version is released.
-