Read ‘The API’ Book by Sergey Konstantinov in English

Читать книгу ‘The API’ Сергея Константинова по-русски

This is the working repository for ‘The API’ book written by Sergey Konstantinov (email, Linkedin profile).

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 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.

Current State and the Roadmap

Right now all three section (‘The API Design’, ‘The Backwards Compatibility’, and ‘The API Product’) are finished. So the book is basically ready. However, after some beta-testing I understood there were several important problems.

1. 'Describing final interfaces' chapter is way too overloaded; many concepts explained there deserve a separate chapter, and being minimized to fit the format, they arise a lot of controversy.
2. Though I've tried to avoid talking about any specific paradigm (REST in particular), it's often being read as such, thus igniting discussions on whether the samples are proper REST.

So the current plan is:

1. To split Chapter 11 into a full Section III (work title: 'API Patterns') comprising:
   • defining API-first approach in a technical sense;
   • the review of API-describing paradigms (OpenAPI/REST, GraphQL, GRPC, JSON-RPC, SOAP);
   • working with default values, backwards compatibility-wise;
   • (a)synchronous interaction;
   • strong and weak consistency;
   • push and poll models;
   • machine-readable APIs: iterable lists, cursors, observability;
   • an amount of traffic and data compression;
   • API errors: resolvability, reduction to defaults;
   • degrading properly.
2. To compile Section IV ‘HTTP API & JSON’ from current drafts + HTTP general knowledge + codestyle.
3. Maybe, try to compile Section V ‘SDK’ (much harder as there are very few drafts).

Also, the book still lacks the readable schemes which I'm still planning to plot with mermaid.

Translation

I am translating new chapters into English at the moment they're ready. I'm not a native speaker, so feel free to correct my grammar.

Contributing

I am accepting inquiries. Feel free to open issues.

I am NOT accepting pull requests introducing any new content, since I'm willing to be the only author. I would gratefully accept typo fixes, though.

Thanks art.mari.ka for the illustration & inspiration.

Thanks Ilya Subbotin and Fedor Golubev for the valuable feedback.

Thanks @tholman for https://github.com/tholman/github-corners.

Thanks Ira Gorelik for the Aqueduct.

Thanks ParaType for PT Sans and PT Serif.

Thanks Christian Robertson for Roboto Mono.