---
title: "Introducing the Heroku HTTP API Toolkit"
description: "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."
---

# Introducing the Heroku HTTP API Toolkit

[Heroku](https://yomu.fyi/company/heroku) · Wesley Beary · May 15, 2014

**Type:** Announcement

## 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.

## Context

Heroku uses the guide to increase API consistency and quality, reduce time spent debating design details, and support shared practices across user-facing and internal services. JSON Schema and generated documentation also help structure discussions about new APIs and changes to existing ones.

## Approach / What changed

The toolkit combines an HTTP API Design Guide, the prmd JSON Schema management tool, and auto-generating clients for Ruby and Go. prmd bootstraps schemas, verifies completeness, and generates documentation; Heroics and Schematic generate clients from those schemas.

## Takeaways

- The design guide covers versioning, resource structure, attribute naming, serialization, error handling, request IDs, pagination, and caching support.
- prmd provides commands to initialize JSON Schemas, verify a schema directory, and generate documentation from the specifications.
- Heroku uses JSON Schema, prmd, and Heroics for the Heroku Platform API, and is increasingly applying the toolkit to internal services.

**Tags:** [API](https://yomu.fyi/topic/api), [Go](https://yomu.fyi/topic/go), [JSON Schema](https://yomu.fyi/topic/json-schema), [Ruby](https://yomu.fyi/topic/ruby)

- Source: [Heroku](https://www.heroku.com/blog/http-api-toolkit)
- Source URL: https://www.heroku.com/blog/http-api-toolkit
- Ingested by Yomu: 2026-09-09T14:22:56.773Z

[Read original post](https://www.heroku.com/blog/http-api-toolkit)