learn-api-design: the dwyl house guide to building an API

A repository with a README and nothing else

The top level listing of learn-api-design contains a .gitignore and a README.md. That is the entire repository. There is no source directory, no test suite, no package manifest, and the project record lists the primary language as unknown because there is no code to classify.

So the first thing to be clear about is that this is a document, not a tool. Nobody installs it, nobody depends on it, and there is no API to call. The repository description calls it essential learning for people building APIs, and the README header says it is about building an API that is performant, scalable and maintainable.

The last push to the repository was on 2026-07-09 and it is not archived. There are no GitHub releases, which is consistent with a repository whose only artefact is a file that changes when somebody adds a section or corrects a paragraph. The licence field on the project record is unknown and there is no LICENSE file in the listing, so the terms for reuse of the text are not stated in the repository itself. If you plan to copy sections into a design standard at work, that is the first question to settle, and it is a question for the maintainers rather than for this page.

The interesting thing about a guide like this is who wrote it and for whom, and the README is direct about both. It says the guide is meant as an internal reference for the dwyl team, that everyone in the team or community should read it, understand it and attempt to improve or extend it, and at the same time it is a fully open source resource that anyone can read and learn from. Contributions are welcome through issues, and the invitation to star the repository is part of the text rather than a side note.

That dual purpose explains the shape of the document. It is written to be argued with.

The argument for taking API design seriously before you start

The README opens with a metaphor about a golden ticket and a grandmother, and then drops it to make a point: starting a project from scratch is an opportunity and a privilege that few people get, so do the homework before you start.

The reasoning underneath is stated in the Why section. Having a great API will make or break the project, and the authors expect a significant percentage of the people using their application to access the API, either for automation such as through a voice assistant, or simply to extract, analyse and visualise their data. The conclusion drawn is that the API is the product.

That framing has a consequence for how much effort goes into the document. If the API is the product, then the API's users are not an internal team who can be asked to look at the source, and the document treats them as strangers with automation scripts.

The guiding quotes section borrows from two talks, Joshua Bloch's How To Design A Good API and Why it Matters and Kevin Lacker's How to Design Great APIs. The quotes chosen are the sharp ones. You have one chance to get it right. A bad API can be among a company's greatest liabilities, can cause an unending stream of support phone calls, and can inhibit a company's ability to move forward. Once you have a bad API you cannot change it, you are pretty much stuck with it forever.

The two quotes that stand out as the most useful are the ones about behaviour. A good API needs to appeal to laziness, which is a roundabout way of saying the caller should not have to work to use it. And the user of an API should never be surprised by its behaviour, with the note that it is sometimes worth reduced performance rather than surprising users of the API. That is the whole philosophy of the document in two lines, and it explains why the later sections are so prescriptive about error shapes and response codes.

What counts as a good API, in eight bullets

The characteristics section is a short list, and it is the most quotable part of the guide. Easy to learn, with the guide noting the priority placement of learnability. Intuitive and easy to use even without documentation. Hard to misuse, with the parenthetical instruction to write tests for undesirable behaviour. Easy to read and maintain code that uses it. Capable enough to satisfy requirements. Easy to evolve, with the observation that the simpler the initial API, the easier it will be to extend. Appropriate to the audience, with the advice to make it beginner friendly. And opinionated.

Two of those deserve comment because they are the ones teams tend to argue about.

Hard to misuse with tests for undesirable behaviour is the strongest idea in the list, and it is the one most often dropped. A permissive API that lets a caller send a negative quantity, or a start date after an end date, or a currency code that is not a currency, pushes the error to the worst possible moment. The list is saying that the cases where the API is misused are cases you should write tests for and then close off, so that the caller cannot reach them in the first place.

Opinionated is listed as a virtue rather than a flaw, and the Lacker quote in the guide explains it: you need to be opinionated even when there is no right and wrong. The guide is explicit that there are areas where the choice is a house style decision, and a house style that everyone can predict is worth more than a theoretically optimal design that surprises half the callers.

The audience point is the one that connects back to the Why section. If a significant percentage of your users will script against your API, then beginner friendly is not politeness, it is a requirement, because those users are not going to read your documentation and then ask a colleague what to do when the error message is unclear.

REST, RPC, SOAP and WebSockets are placed in one history

The guide walks through the types of API in a quick history lesson, covering RPC, SOAP, REST and then realtime APIs using WebSockets, with examples of successful RESTful APIs and of realtime APIs along the way.

The structure is worth noting. The types are presented as a progression rather than as competing options to pick between at the start of a project, and the REST section within it is broken into what a RESTful web service is and which HTTP methods to use for RESTful services. The realtime section is treated as an addition to that rather than a replacement, since the guide covers both and puts examples of each next to the concept.

The section list for the practical half of the guide is where the bulk of the content sits, and it is effectively a design checklist:

Providing sensible resource names. Using adequate HTTP response codes to indicate status. Using query parameters to filter, sort or search resources, with subsections for filtering and sorting, for searching, and for limiting the fields returned in the JSON response. Showing meaningful errors. Favouring JSON over XML support. Avoiding chattiness in the API. Considering connectedness. Always using SSL. Linting responses and adding gzip support. Accepting JSON in POST, PATCH and PUT bodies. Pagination. Rate limiting. Caching. Versioning, with subsections for URI versioning, header versioning and media type versioning, and a section asking which one should I choose. Then API documentation, API testing and API monitoring.

The ordering is a design argument. Naming, status codes and filtering are what a client developer hits in the first hour. Errors, chattiness and field limiting are what make a client brittle. SSL, gzip, pagination, rate limiting and caching are the operational layer. Versioning and documentation come last because they follow from the shape of everything before them.

The versioning question gets three answers and no verdict

One section of the guide deserves separate attention because it is the clearest example of how the document handles genuine trade-offs rather than pretending they do not exist.

Versioning your API is broken into three approaches. URI versioning, where the version appears in the path. Header versioning, where the client sends a version in a request header. And media type versioning, where the version is negotiated through the content type of the response. The section then asks which one should I choose.

The presence of that question as its own heading is itself the answer. A document that simply asserted one approach would be less useful than one that lays out the three and asks the reader to decide, and it is consistent with the Lacker quote about being opinionated even when there is no right and wrong. Being opinionated means choosing one and documenting it, not that the choice is obvious.

The other sections are similar in character. Avoiding chattiness in the API is a rule about how many round trips a client needs, and the client side of that trade is where the guide's laziness principle points. Considering connectedness is about resources that refer to other resources. Limiting the fields returned in the JSON response, the guide notes, is about not making the caller download data it does not need, which is the same principle applied to payload size rather than to call count.

The closing operational sections, API documentation, API testing and API monitoring, are grouped together as the last three items. That grouping is a statement about lifecycle. The earlier sections decide the shape, and these three decide whether the shape stays true over years.

Where a house guide stops and a specification starts

The honest limitation of this repository is that it is a curated reading of other people's ideas, and it is not complete.

Start with what the section list does not contain. There is no section on authentication or authorisation, on API keys or tokens, on multi-tenant data separation, on rate limit key derivation, or on secrets management. Those are not peripheral topics in API design; for a public or multi-tenant API they are the majority of the design surface, and a reader who works through this guide in full will have covered the resource and transport layer thoroughly while the security model is still blank.

There is also no section on the HTTP specifications themselves. The guide teaches you to use adequate response codes and to use SSL, but it is a guide to judgement rather than a reference to the underlying standards, and it does not give you the semantics of conditional requests, of the range header, or of the exact rules around method safety and idempotency that a correctness argument about caching or retries depends on.

The nature of the sources it draws on is a further constraint. Much of the guide is built on two conference talks, and the API world those talks describe has moved: the ecosystem around GraphQL, gRPC and server-sent events is not discussed in the section list, so a reader who arrives expecting coverage of modern API styles will find a REST and WebSockets centred treatment.

None of this makes the guide wrong, and the fact that it argues from first principles about naming, errors and behaviour is precisely what makes it useful. It makes it a starting document rather than a finished standard.

Editorial conclusion

learn-api-design fits an engineer who is about to design an API and wants a structured checklist of the decisions that are expensive to reverse, and it fits a team that has no house style and would otherwise argue about resource naming and versioning from scratch. It is not a specification, and it is not a substitute for reading the HTTP specifications or the RFCs behind pagination and caching, and it does not cover authentication, authorisation or multi-tenant design in the section list. Before using it as a design document, read the sections on errors, versioning and pagination closely and treat the advice on being opinionated as a decision you have to make rather than a rule you can inherit, because the guide is explicit that there is no right and wrong answer in several of these areas. Confirm the claims it makes about your own stack, since the repository carries no tests and no code to check them against.

Frequently asked questions

Official sources

1. dwyl/learn-api-design on GitHub
2. Issues
3. README