emacsway / The-API-Book

‘The API’ book by Sergey Konstantinov

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

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.