Leanpub Header

Skip to main content

Topics

API Design

From resources, HTTP methods and hypermedia to versioning, GraphQL, WebSockets, gateways, rate limiting, security, testing and the API as a product, API design as told through the free samples of the Leanpub books about it.

Created from the free samples of 11 Leanpub books and the descriptions and tables of contents of 24 more, with every source cited.

An application programming interface, or API, is the surface through which one program uses another, and API design, in the sense of the books here, is the design of interfaces offered over a network, almost always over HTTP, to programs written by other people. The difficulty is that those people cannot be consulted afterwards. One short guide observes that for every interface that is well thought out, documented and pleasant to use there are dozens that are obscure, inconsistent, error-prone and tedious,[12] and a paper on changing interfaces safely begins from the premise that change is inevitable and that every change has a cost, because the coupling between an interface and its clients stays invisible until something breaks.[6]

The dominant style is REST, in which an interface is a set of resources addressed by URL and acted on with the methods of HTTP. One collection takes its title from the remark of the style's originator that it is software design on the scale of decades, in which every detail is meant to promote longevity and independent evolution and many constraints run against short-term efficiency.[13] Around that core the shelf covers the alternatives for queries and for real-time communication, the machinery in front of an interface, its testing, and the business of offering one as a product.

This article covers where to begin, the history, resources and the REST style, guidelines and change, the alternatives to REST, gateways, limits and security, testing and consuming interfaces, building them in particular frameworks, and the API as a product. Its sources are the free samples of the Leanpub books listed at the end, with the descriptions and tables of contents of the books whose samples were not available, and every claim that rests on a source is cited to it.

Where to start

The two general books on design are Build APIs You Won't Hate (2016), a practical guide written from experience of interfaces that have to survive changes in data and in the business,[1] and Simple RESTful API design guidelines that make sense (2024), a cookbook of guidelines in a few pages followed by the reasoning for each.[2] The Web API Design Guidelines for Happy Developers (2016) is a brief set of tips,[12] and API Design on the Scale of Decades (2017) collects conference talks on interfaces meant to last.[13]

Developers who want to build one in a particular language can choose by language: API foundations in Go (2019) for Go,[10] API on Rails 6 (2021) and Ruby on Roda (2021) for Ruby,[21][22] Akka HTTP RESTful APIs (2020) for Scala,[23] and REST HOW TOs (2022) for five languages side by side.[20] SignalR on .NET 6 - the Complete Guide (2022), the most widely sold book in the extract, is the guide to real-time communication on one platform.[3]

Testers have Automating and Testing a REST API (2017), a worked case study,[7] and API Testing Fundamentals: Postman to Pytest, a course from manual exploration to automated suites.[8] Those who operate interfaces have The API Gateway Handbook and API Rate Limiting & Throttling,[4][5] and those responsible for an interface as a business have API Product Management (2021).[27]

History

Programs have called procedures in other programs across a network since the 1970s, and each generation has had its conventions for doing so. The late 1990s produced a family of standards that wrapped such calls in XML documents. In 2000 a doctoral dissertation described the architecture of the web itself as a style, named REST, and argued that interfaces built in the same way, from addressable resources, uniform methods and links, would share the web's capacity to grow and change. Through the 2000s large web companies opened public interfaces in a loose version of that style, JSON displaced XML, and by the 2010s there were description formats, gateways and management products for them. GraphQL and a new generation of remote procedure calls appeared in the middle of that decade as alternatives for particular needs.

The books mark these stages. Simple RESTful API design guidelines that make sense has a chapter on the evolution of interfaces that dates remote procedure calls to 1970, the XML standards to 1998 and REST to 2000, and then treats the technologies outside REST.[2] Beautiful APIs (2021) describes the interfaces it illustrates as coming from the time when many people tried, with very different results, to use HTTP to invoke software delivered as a service.[9] The API Economy (2016) records the point at which the field had, in its words, produced an economy in its own right, with companies supplying components for each stage of an interface's life.[26] GraphQL or Bust (2018) weighs the newer query language against REST in its early years,[16] and the most recent titles are about interfaces read and called by language models.[31][33]

Resources and the REST style

The sample of Build APIs You Won't Hate is its chapter on the part of REST most often left out, known by an unwieldy acronym for hypermedia as the engine of application state, which the author reduces to two things. The first is content negotiation. Some interfaces that call themselves RESTful, the book complains, put a file extension and an identifying parameter in the address, which misuses the idea of a resource and forces the consumer to know the name of an endpoint, to choose a format and to know the parameter; a good interface has one address for the thing itself and lets the request's headers say which representation is wanted, answering with a default or with an error if the format is not supported. Addresses are not folders and file names, and an interface is not a list of files: it is a list of resources that can be represented in different formats.[1]

The second is hypermedia controls, which the book calls drastically underused and the last step in making an interface RESTful in the strict sense. It cites the style's originator, who wrote in 2008 that without them an interface is not RESTful, and an estimate that about three quarters of the interfaces claiming the name do not use them. A widely quoted maturity model has four levels: HTTP used merely as a tunnel for remote calls, then separate resources, then the proper use of methods, then hypermedia. The controls themselves are only links, to other content, to relationships and to further actions, which let a consumer move through an interface and discover what can be done; REST, the author says, is a matter of using the conventions of the web and not inventing new ones.[1]

Beautiful APIs shows what the structure looks like. It is the catalogue of a virtual exhibition in which ninety-three interfaces are drawn as trees, resources as branches with a bulb on each branch for every method that applies to it; the interfaces were chosen for their appearance, and every one existed at some time even if the service behind it is gone.[9] RESTful Dictionary (2022) answers one recurring question, which method to use for an address that represents an action, as a dictionary from English verbs to HTTP methods compiled from the designs of many thousands of interfaces.[14] JSON API By Example (2016) is a short book on building a back end to one published specification for the shape of JSON responses.[15]

Guidelines and change

Simple RESTful API design guidelines that make sense describes itself as purely technical, practical and simple, written for typical systems and not for very large ones with peculiar needs, and validated from the points of view of back-end and front-end developers and of several kinds of architect. A table lists the questions it answers by role: whether to expose database tables or the logical model as resources, what naming conventions to use, whether the interface supports what a user interface needs, such as pagination and sorting, what to test, whether the vocabulary of the domain should appear in the interface, and how to check that nothing sensitive is exposed. The cookbook begins with principles, among them resources identified by address, several representations of each, a stateless server, the proper semantics of HTTP, and responses labelled as cacheable or not, and then rules. The version goes in a segment of the path and only the major number is used; a change that is backward compatible replaces the running version invisibly, while one that is not is deployed beside the old version for a period in which clients can migrate. All resources are modelled as things to be created, read, updated and deleted, and interfaces expressed as intentions are converted to that form. A later chapter reviews the maturity models in order to decide how mature an interface should be, balancing maturity against simplicity.[2]

Handy API Extension Patterns, a short paper, is about the commonest change of all. Even adding a field to a JSON response can cause failures: a mobile application with a parser written by hand treats the message as malformed and crashes; an automated pipeline silently discards the new property; a form bound directly to known fields throws errors when one is renamed; a client in a compiled language has the shape of the response built into a generated type and must be regenerated, retested and redeployed. These, the author says, are the stories heard again and again. The question is not whether an interface will change but how to change it without breaking what surrounds it, and the paper's answer is one pattern for extending responses, built on pairs of names and values and on messages that are, in its term, mildly typed.[6]

GraphQL, real-time interfaces and remote calls

REST suits resources that are fetched and changed one at a time. GraphQL or Bust is an anthology on the query language that lets a client ask in one request for exactly the data it wants: its benefits, its differences from REST, its particular security concerns, its tooling and the transition from an existing interface.[16] Turn Pro in GraphQL (2019) is a very short book that sets out to go from the basics to its use across many services.[17]

SignalR on .NET 6 - the Complete Guide is about interfaces in which the server speaks first. The WebSocket protocol, it explains, was designed for two-way communication: once a connection is open, messages can flow in both directions for as long as it lasts, and keeping it open costs little. But the protocol carries raw bytes, so that assembling and taking apart messages and watching the state of the connection are left to the developer. The library that is the book's subject hides this, and the author compares using it to making classes within one application call each other's methods: the server has ordinary methods, the client names them, and the reverse works through listeners on the client. It uses the WebSocket protocol when it can and falls back first to events sent by the server and then to long polling.[3]

Two adjacent books cover other forms. Advent of Go Microservices (2020) builds services in Go that call one another by a modern form of remote procedure call, generating the repetitive code,[32] and MCP Servers with OAuth is a short introduction to servers that expose tools to language models over HTTP with delegated authorisation.[33]

Gateways, limits and security

The API Gateway Handbook is a handbook on the component that stands in front of a set of interfaces. Among the functions it lists are the transformation of messages from one format to another, orchestration, in which the gateway combines the responses of several services into one, the balancing of load across servers, and inventory, the visibility into which interfaces are exposed, how they are used and which are out of date. With more than sixty products in one catalogue the choice is hard, and the book sorts them into kinds: gateways at the edge of the network, placed near users for applications that cannot tolerate delay; those offered by the large cloud providers, which can front serverless functions; libraries that embed a gateway in an application; and those built for container platforms.[4]

API Rate Limiting & Throttling calls itself a field manual and gives separate reading paths to engineering leaders, architects, software engineers and operators. Rate limiting, it says, is not a product feature fastened to the edge but a contract for shedding load: it defines who may consume capacity, how quickly, and what happens when demand exceeds the budget. Its operating principle is that the limiter must fail before the dependency it protects; if the database is already saturated when rejections begin, the limiter is late, and the right signal is that denials started while the system was still healthy. In a distributed system the algorithm matters less than the questions round it, and above all the key by which requests are counted, which the book calls the fairness boundary. Good keys are stable, bounded and meaningful, such as a tenant, an API key or a user; bad ones are a bare network address, an unvalidated header or a single key for the whole service.[5]

Identity And APIs (2022) collects articles on security built round identity, covering a maturity model for it and the standards for delegated access and for login.[18]

Testing and consuming interfaces

Automating and Testing a REST API is a case study in automating the testing of an open-source application without going through its graphical interface. The author's reasons are that working beneath the interface is faster and can do things the interface cannot, and the book extends the idea beyond the published API to what it calls the application as API, sending the HTTP that the pages would have sent. It is frank about the cost: here the graphical route would have been easier, with no sessions to manage and no data to scrape from pages. The study shows quick and crude code first and then its improvement, and explains at each step why a decision was made and what else could have been done.[7]

API Testing Fundamentals: Postman to Pytest starts from the rule that an interface should be understood before its tests are automated, exploring it by hand in a graphical client, and proceeds to automated suites run on every change, the validation of responses beyond their status codes, the testing of authentication, errors and limits, the query language and remote calls, and versioning.[8] From the consumer's side, Surviving Other People's APIs (2023) is about building applications on interfaces that are poorly documented or slow, on the premise that anything done over a network can fail unexpectedly,[19] and the first part of REST HOW TOs shows how interfaces are called from each of its five languages.[20]

Building interfaces in a framework

Several books are tutorials in one language or framework, framed round the building of an interface. API foundations in Go is for senior developers who know the concepts from other languages and have not tried Go; it does not teach the language, and covers the organisation of code, JSON, the serving of requests, the fetching of data in parallel, external stores, test-driven development and production. Its author moved to Go in order to replace the software round a code base thirteen years old while keeping the working code.[10] API on Rails 6 builds a RESTful interface step by step in Ruby's best-known framework,[21] and Ruby on Roda builds one with a smaller routing framework and a database toolkit, which its description presents as a way to cleaner code.[22] Akka HTTP RESTful APIs builds a bookshop's interface in Scala test first,[23] Programming APIs with the Spark Web Framework (2015) uses a small Java framework,[24] and Phoenix Product Codex (2025) is an account, still in progress, of an interface for product data in Elixir.[25]

The API as a product

A group of books, several of them anthologies from one blog and conference series, treat the interface as something sold. The API Economy collects articles and case studies on the business that has grown up round interfaces.[26] API Product Management sets out a method for creating, launching and running an interface as a product,[27] API as a Product (2022) gives advice on a business whose product is its interface,[28] How to Successfully Market an API (2016) is on planning, developer relations and promotion,[29] and Developer Experience (2022) argues that the experience of the developers who use an interface is what separates services that are adopted from those that are not, and covers discovery, onboarding and self-service.[30]

API Strategy for Open Banking (2020) is the case of a regulated industry. Open banking standards, its foreword explains, are implemented as sets of open interfaces of two main kinds, one for information about an account and one for moving money, and whether the impetus is regulation or the market the aim is a common standard by which all the parties can communicate; the foreword argues that consumers, governments, technology companies and banks all gain.[11] Tokens Not Jokin' reports more than twenty-one thousand integration tests, across four language models and two interfaces, of whether the format of documentation affects the cost and quality of generated code.[31] Two adjacent books complete the picture: API-Driven DevOps (2016) on delivery practices organised round interfaces,[34] and Design Practice Reference (2025), a reference of activities, templates and roles for the analysis and design of services.[35]

Questions about API Design

Which API design book should I start with?

The two general books on design are Build APIs You Won't Hate, a practical guide from 2016 written from experience of interfaces that have to survive changes in data and in the business, and Simple RESTful API design guidelines that make sense, a 2024 cookbook of guidelines in a few pages followed by the reasoning for each.[1][2] Developers who want to build an API in a particular language can choose by language, with API foundations in Go for Go and API on Rails 6 for Ruby.[10][21]

What makes an API RESTful?

A widely quoted maturity model has four levels: HTTP used merely as a tunnel for remote calls, then separate resources, then the proper use of methods, then hypermedia.[1] The last step is hypermedia controls, links to other content, to relationships and to further actions, and Build APIs You Won't Hate cites an estimate that about three quarters of the interfaces claiming the name do not use them.[1]

How should I version a REST API?

Simple RESTful API design guidelines that make sense puts the version in a segment of the path and uses only the major number.[2] A change that is backward compatible replaces the running version invisibly, while one that is not is deployed beside the old version for a period in which clients can migrate.[2]

Can adding a field to a JSON response break API clients?

Yes. Handy API Extension Patterns lists the failures: a mobile application with a parser written by hand treats the message as malformed and crashes, an automated pipeline silently discards the new property, and a client in a compiled language must be regenerated, retested and redeployed.[6] The paper's answer is one pattern for extending responses, built on pairs of names and values.[6]

What is the difference between REST and GraphQL?

REST suits resources that are fetched and changed one at a time, each addressed by URL and acted on with the methods of HTTP, while GraphQL is a query language that lets a client ask in one request for exactly the data it wants. GraphQL or Bust is an anthology on its benefits, its differences from REST, its particular security concerns and the transition from an existing interface.[16]

What is API rate limiting?

API Rate Limiting & Throttling defines rate limiting as a contract for shedding load: it says who may consume capacity, how quickly, and what happens when demand exceeds the budget.[5] Its operating principle is that the limiter must fail before the dependency it protects, and it prefers keys that are stable, bounded and meaningful, such as a tenant, an API key or a user, to a bare network address.[5]

Sources

Every source is a Leanpub book. The note after each says which part of it was read; where no sample was available, only the public description and table of contents were used.

  1. 1.
    Build APIs You Won't Hate, Phil Sturgeon: Everyone and their dog wants an API, so you should probably learn how to build them. Free sample: the chapter on content negotiation and hypermedia controls. 2016. Free sample: PDF · EPUB
  2. 2.
    Simple RESTful API design guidelines that make sense, Michalis ARGYRIOU: that Developers will (want to) use Free sample: the contents, the introduction and the opening of the cookbook. 2024. Free sample: PDF
  3. 3.
    SignalR on .NET 6 - the Complete Guide, Fiodar Sazanavets, Awal Kamin Salifu: The easiest way to enable real-time two-way HTTP communication on .NET 6 Free sample: the opening chapter, on real-time communication and what the library does. 2022. Free sample: PDF · EPUB
  4. 4.
    The API Gateway Handbook, Thomas Bayer, Tobias Polley: Your Practical Guide to API Gateway Setup, Security, and Operation Free sample: part of the chapter on what gateways do and the kinds there are. 2026. Free sample: PDF
  5. 5.
    API Rate Limiting & Throttling, Luca Sepe: Distributed Quotas, Kubernetes Protection, Tenant Fairness, and Go Middleware Free sample: selected pages on the book's purpose, its operating principle and distributed limiting. 2026. Free sample: PDF
  6. 6.
    Handy API Extension Patterns, Mike Amundsen: How to Evolve Message Formats Without Breaking Everything Free sample: the opening and the conclusion of a short paper; the middle sections are withheld. 2026. Free sample: PDF · EPUB
  7. 7.
    Automating and Testing a REST API, Alan Richardson: A Case Study in API testing using: Java, REST Assured, Postman, Tracks, cURL and HTTP Proxies Free sample: the introduction, on the case study and its approach. 2017. Free sample: PDF · EPUB
  8. 8.
    API Testing Fundamentals: Postman to Pytest, Yuri Syuganov: From Postman Exploration to Automated REST, GraphQL, and gRPC Pipelines Free sample: the introduction, the contents and the opening of chapter one. 2026. Free sample: PDF
  9. 9.
    Beautiful APIs, Cesare Pautasso Free sample: the preface and a few of the diagrams. 2021. Free sample: PDF
  10. 10.
    API foundations in Go, Tit Petric: You've mastered PHP and are looking at Node.js? Skip it and try Go. Free sample: the introduction, on why Go and for whom. 2019. Free sample: PDF · EPUB
  11. 11.
    API Strategy for Open Banking, Nordic APIs: Insights and case studies from leading open banking experts and API strategists. Free sample: the foreword. 2020. Free sample: PDF · EPUB
  12. 12.
    The Web API Design Guidelines for Happy Developers, Antonio Pintus, Federico Pinna: A short pragmatic guide to build effective and funny Web APIs No sample: from the description and table of contents. 2016.
  13. 13.
    API Design on the Scale of Decades, Nordic APIs: Learn How to Architect and Design Long-lasting APIs No sample: from the description and table of contents. 2017.
  14. 14.
    RESTful Dictionary, Cesare Pautasso: English - HTTP No sample: from the description. 2022.
  15. 15.
    JSON API By Example, Adolfo Builes No sample: from the description and table of contents. 2016.
  16. 16.
    GraphQL or Bust, Nordic APIs: To Use it Or Not to Use It? That is The Question. No sample: from the description and table of contents. 2018.
  17. 17.
    Turn Pro in GraphQL, Johannes Kling No sample: from the description and table of contents. 2019.
  18. 18.
    Identity And APIs, Nordic APIs: Techniques to Mature Platform Security No sample: from the description and table of contents. 2022.
  19. 19.
    Surviving Other People's APIs, Phil Sturgeon, Mike Bifulco: Working with some API can feel like an dangerous expidition into an ancient tomb full of booby traps and archaic instructions. Let's dodge all the pits of spikes and get to the treasure. No sample: from the description. 2023.
  20. 20.
    REST HOW TOs, A.P. Rajshekhar, Shrikant Khare: Consuming and Building REST API in Python, Ruby, Java, C# and Go No sample: from the description and table of contents. 2022.
  21. 21.
    API on Rails 6, Alexandre Rousseau: Learn best practice to build an API using Ruby on Rails 6. The intention with this book it’s not only to teach you how to build an API with Rails. The purpose is also to teach you how to build scalable and maintainable API with Rails which means improve your current Rails knowledge. In this book you will learn to: - Use Git for version control - Building JSON responses - Test your end-points with unit and functional tests - Set up authentication with JSON Web Tokens (JWT) - Optimize and cache the API The free sample is front matter: from that and the description. 2021. Free sample: PDF
  22. 22.
    Ruby on Roda, Mateusz Urbański: REST APIs with Roda & Sequel No sample: from the description and table of contents. 2021.
  23. 23.
    Akka HTTP RESTful APIs, Codemunity: Building Reactive RESTful APIs with Scala and Akka The free sample covers setup only: from that and the description. 2020. Free sample: PDF · EPUB
  24. 24.
    Programming APIs with the Spark Web Framework, Nordic APIs No sample: from the description and table of contents. 2015.
  25. 25.
    Phoenix Product Codex, Isaak Tsalicoglou: Develop and deploy a REST API for Product Data Management with Elixir and Phoenix The free sample is front matter: from that and the description. 2025. Free sample: PDF · EPUB
  26. 26.
    The API Economy, Nordic APIs: Disruption and the Business of APIs No sample: from the description and table of contents. 2016.
  27. 27.
    API Product Management, Andrea Zulian, Amancio Bouza: Product Strategy and Execution for the Digital Economy No sample: from the description and table of contents. 2021.
  28. 28.
    API as a Product, Nordic APIs: Tips for Running an API-centric SaaS Business No sample: from the description and table of contents. 2022.
  29. 29.
    How to Successfully Market an API, Nordic APIs: Fine-Tuning Developer Relations & Platform Advocacy No sample: from the description and table of contents. 2016.
  30. 30.
    Developer Experience, Nordic APIs: Top strategies to improve the developer experience of your API No sample: from the description and table of contents. 2022.
  31. 31.
    Tokens Not Jokin', Ed Grzetich: How API Documentation Format Affects AI Code Generation No sample: from the description and table of contents. 2026.
  32. 32.
    Advent of Go Microservices, Tit Petric The free sample was not used: from the description and table of contents. 2020. Free sample: PDF · EPUB
  33. 33.
    MCP Servers with OAuth, Zach Silveira: An 80 page introduction to MCP, from zero to deployment in one weekend No sample: from the description and table of contents. 2026.
  34. 34.
    API-Driven DevOps, Nordic APIs: Strategies for Continuous Deployment No sample: from the description and table of contents. 2016.
  35. 35.
    Design Practice Reference, Olaf Zimmermann, Mirko Stocker: Activities and Templates to Craft Quality Software in Style No sample: from the description and table of contents. 2025.

Further reading

Other books in the library on neighbouring ground, not cited above.

This is an article created from the free samples of 11 Leanpub books and the descriptions and tables of contents of 24 more. We're building these articles to provide you, the Leanpub reader, with a good jumping-off point to discover more Leanpub books that are interesting and relevant to you. We never use material which is paid-only when building these articles: we only use material which is already free on Leanpub. However, Leanpub authors can opt out from inclusion in articles from their book settings page.

Updated November 2026.

In the Leanpub store: 213 books · 2 courses in the APIs category · also filed under API Design, Websockets

All topics