The API Book

This is the working repository for ‘The API’ book, being written by Sergey Konstantinov.

You may find .html or .pdf version of the book [NB: Warning! Work in progress] in the 'docs' folder, or at https://twirl.github.io/The-API-Book/docs/API.ru.html (Russian version).

The book is distributed under Creative Commons Attribution-NonCommercial 4.0 license, meaning in general that you're totally free to use this book in any manner while complying with two rules:

• you're not getting commercial profit from the book;
• you're not forgetting to mention the author.

See full license in LICENSE.md file or at Creative Commons Website.

Current State and the Roadmap

Right now Section I (‘API Design’) is finished. The Section is lacking readable schemes, I'll draw them later.

Book will contain two more sections.

• Section II ‘Backwards Compatibility’ will cover growth issues. Major themes are:
  • major sources of problems leading to backwards compatibility breach;
  • interface decomposing allowing for third-party plugins and switching underlying technologies;
  • structuring public and private parts of your API;
  • versioning policies;
  • common mistakes.
• Section III ‘API as a Product’ will be discussing non-technical issues:
  • what for the APIs exist;
  • monetizing APIs;
  • making sure your understand users' needs and collect proper metrics;
  • common practices, including AA issues and fraud problems;
  • organizing docs portal;
  • open source and community.

I also have more distant plans on adding two more subsections to Section I.

• Section Ia ‘JSON HTTP APIs’:
  • the REST myth;
  • following HTTP spec, including those parts where you should not follow the spec;
  • best practices;
• Section Ib ‘SDK Design’ covering more tricky issues of having proving UI alongside the API (no specific plan right now)

Translation

I will translate sections into English at the moment they're ready. Which means that Section I will be translated soon.

Contributing

I am accepting any inquiries. Fill free to open issues.

I am NOT accepting pull requests, since I'm willing to be the only author and contributor.