Introducing the Heroku HTTP API Toolkit

Today we’re open sourcing the toolchain Heroku uses to design, document, and consume our APIs. We hope this shows how Heroku thinks about APIs and gives you new tools to create your own APIs.

This toolkit includes our HTTP API design guide, the prmd tool for managing JSON schemas and generating API docs, and client generators for Ruby and Go.

Here’s some more information about these things, how we use them at Heroku, and an explanation of how you can try them yourself.

HTTP API Design Guide

The Heroku HTTP API Design Guide shows how we design and document APIs at Heroku.

We use this guide to increase the consistency and quality of the APIs we deliver, both for our user-facing product and for internal services. A concrete guide also minimizes time spent bikeshedding about API design details and maximizes time spent on actual business logic of our apps.

This document includes guidance on versioning, resource structure and attribute naming, serialization, errors handling, request ids, pagination, and caching support. It also describes how we use the JSON Schema standard to describe our APIs in a machine-readable way, and use those schemas to generate API documentation.

This document is a work in progress. We welcome discussion and contributions; feel free to open an issue on the GitHub repository.

Schema and Documentation Toolchain

The JSON Schema format provides a great machine-readable description of an API. As a complement to this, the JSON Schema management tool prmd ("pyramid") helps you bootstrap a schema description, verify its completeness, and generate documentation from the specification.

For example:

$ prmd init app > schema/app.json
$ vi schema/app.json
$ prmd verify schema
$ prmd doc schema > schema.md

Auto-generated Clients from API Schemas

One benefit of JSON Schemas is being able to automatically create API clients for any service. These clients help you quickly get started with an API in the language of your choice, and can also increase consistency of client usage across different services.

We’ve developed example auto-generating clients for both the Ruby and Go languages.

Here’s an example of using the Ruby client Heroics to access the Heroku Platform API:

api_token = '...'
url = 'https://:#{api_token}@api.heroku.com'
opts = {default_headers:
  {'Accept': 'application/vnd.heroku+json; version=3'}}
data = JSON.parse(File.read(schema.json))
schema = Heroics::Schema.new(data)
client = Heroics.client_from_schema(schema, url, opts)
client.apps

An here’s a comparable example of generating a Go client with Schematic:

$ go get github.com/heroku/schematic
$ curl -o api.json https://api.heroku.com/schema -H "Accept: application/vnd.heroku+json; version=3"
$ schematic api.json > heroku.go

Usage at Heroku

We’ve been using this toolkit at Heroku for both user-facing and internal APIs.

For example, this toolkit draws heavily from the new Heroku Platform API we recently released. We use JSON schema to describe this API, prmd to generate API docs in Dev Center, and Heroics for our Ruby client to the API.

We’re also increasingly using this toolkit for our internal services. We find that having symmetry between our external and internal APIs increases our ability to reuse design practices and tooling, and also helps us raise the quality bar on our internal APIs.

At a higher level, JSON schema and associated generated docs are emerging within Heroku as a shared language that we can use to talk about API designs. To propose a new API or a change to an existing one, we present a JSON schema or a diff against an existing one, respectively. This practice sharpens our API design discussions and makes it easier to avoid miscommunications.

We’d love to see more external adoption of this toolkit and welcome discussion and feedback about it.

Summary

Well-designed and documented APIs are a great investment. The API toolkit described here can help you deliver them. We hope you’ll check out the design guide, try out the prmd JSON schema toolkit, and experiment with auto-generated API clients like Heroics and Schematic. We’d love to hear your feedback; please send it to api-feedback@heroku.com.

Video Transcript