http-api-design

This repository is a written guide for designing HTTP APIs, the kind of interfaces that let software applications talk to each other over the web. It started as an internal document at Heroku, drawn from real decisions made while building the Heroku Platform API. Heroku later published it openly so other developers could use the same conventions.

The guide is a collection of opinionated recommendations about how to structure an API: what URLs should look like, how to handle errors, how to version an API over time, and similar questions that every team building a web API has to answer. The stated goal is consistency, not finding the single perfect answer to every question. The authors wanted a shared set of rules that a team could agree on and stop debating repeatedly, which they describe as avoiding "bikeshedding" (spending too much time arguing about small stylistic choices).

The actual guide content lives in the repository as text files rather than code. Reading it is easiest through the GitBook link mentioned in the README, which renders the chapters in a more readable format. The guide assumes the reader already knows what HTTP and JSON are and covers how to apply them well rather than explaining the basics.

The repository has been translated by volunteers into Italian, Korean, Portuguese, Spanish, Turkish, Traditional Chinese, and Simplified Chinese, suggesting it found an audience among developers worldwide. Contributions to the guide are welcome through the standard GitHub pull request process.