Repository files navigation

This guide describes a set of HTTP+JSON API design practices, originallyextracted from work on theHeroku Platform API.

This guide informs additions to that API and also guides new internalAPIs at Heroku. We hope it’s also of interest to API designersoutside of Heroku.

Our goals here are consistency and focusing on business logic whileavoiding design bikeshedding. We’re looking fora good, consistent,well-documented way to design APIs, not necessarilythe only/idealway.

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

Available for online reading and in multiple formats atgitbook.

We welcomecontributions to this guide.

SeeSummary for Table of Contents.

For the best reading experience, we recommend reading viaGitBook.

• English
• Italian (based onf12db3e), by@diegomariani
• Simplified Chinese (based on40d114b), by@ZhangBohan

• Korean (based onf38dba6), by@yoondo
• Portuguese (based onfba98f08b5), by@Gutem
• Simplified Chinese (based on337c4a0), by@ZhangBohan
• Spanish (based on2a74f45), by@jmnavarro
• Traditional Chinese (based on232f8dc), by@kcyeu
• Turkish (based onc03842f), by@hkulekci