http-api-design README

The project's README from github.com/interagent/http-api-design. As one markdown file: README.md.

HTTP API Design Guide

This guide describes a set of HTTP+JSON API design practices, originally extracted from work on the Heroku Platform API.

This guide informs additions to that API and also guides new internal APIs at Heroku. We hope it’s also of interest to API designers outside of Heroku.

Our goals here are consistency and focusing on business logic while avoiding design bikeshedding. We’re looking for a good, consistent, well-documented way to design APIs, not necessarily the only/ideal way.

We assume you’re familiar with the basics of HTTP+JSON APIs and won’t cover all of the fundamentals of those in this guide.

Available for online reading and in multiple formats at gitbook.

We welcome contributions to this guide.

See Summary for Table of Contents.

For the best reading experience, we recommend reading via GitBook.

Gitbook Translations

Git Translations

http-api-design (interagent/http-api-design)

Searching Database…

13.7K ·GitHub
Http-api-design
What is this?A guide to HTTP+JSON API design practices, extracted from work on the Heroku Platform API, covering things like resource naming, versioning, error handling, and pagination.
Is this a library or just documentation?It's a written guide (a book/document), not code you install or run.
How do I read it?Read it online via GitBook for the best experience, or browse the Markdown source in the repo starting from the Summary table of contents.
Is this the 'only right way' to design APIs?No, the authors explicitly say it's one consistent, well-documented approach, not necessarily the only or ideal one.
Who is this guide for?API designers, originally written for Heroku's internal and platform APIs but intended to be useful to any HTTP+JSON API designer.
Do I need prior HTTP/JSON knowledge to follow this guide?Yes, the guide assumes familiarity with HTTP+JSON API basics and does not cover those fundamentals.
Is the guide available in languages other than English?Yes, there are community translations including Italian, Simplified and Traditional Chinese, Korean, Portuguese, Spanish, and Turkish.
Why was this guide created?It was extracted from real design decisions made on the Heroku Platform API, aiming for consistency across APIs while avoiding endless design bikeshedding.
What are similar projects?git-flight-rules, docker-cheat-sheet, api-guidelines, naming-cheatsheet, github-cheat-sheet, python-cheatsheet, learnxinyminutes-docs, rust-learning
Which topics is it in?best-practices, http, json, reference, guide, documentation, rest-api, list, markdown, tutorial, resources, education
Creator
interagent
Size
0.2 MB
Stars
13.7K
Updated
CommitJan 16
Age
12y
Commits · 90 Days