Introducing the Heroku HTTP API Toolkit

Summary

Heroku is open sourcing the toolchain it uses to design, document, and consume HTTP APIs, covering a design guide, JSON Schema tooling, and generated Ruby and Go clients. The guide addresses versioning, resource structure, naming, serialization, errors, request IDs, pagination, and caching, while prmd can bootstrap schemas, verify completeness, and generate documentation. JSON Schemas also drive client generation through Heroics for Ruby and Schematic for Go, with examples showing access to the Heroku Platform API and generation from its schema. Heroku says the toolkit supports both user-facing and internal services, where shared schemas and generated documentation provide a common language for proposing APIs or changes and help align design practices.

Takeaways

1. 1

   The design guide covers versioning, resource structure, attribute naming, serialization, error handling, request IDs, pagination, and caching support.

2. 2

   prmd provides commands to initialize JSON Schemas, verify a schema directory, and generate documentation from the specifications.

3. 3

   Heroku uses JSON Schema, prmd, and Heroics for the Heroku Platform API, and is increasingly applying the toolkit to internal services.