JSON Schema for Platform API

Last updated 27 May 2020

The Heroku Platform API has a machine-readable JSON schema that describes what resources are available via the API, what their URLs are, how they are represented and what operations they support. Example intended uses for the schema include:

• Auto-creating client libraries for your favorite programming language
• Generating up-to-date reference docs
• Writing automatic acceptance and integration tests

A number of Platform API client libraries are already being generated using the schema:

• platform-api for Ruby
• node-heroku-client for Node.js
• Heroku.scala
• and heroku-go

Format

Heroku uses JSON Schema to describe the Platform API. The draft Validation and Hypertext extension standards are also used.

JSON Schema is also used as the basis for Swagger and the Google API discovery service and the JSON Schema website lists many resources and links that demonstrate how to get started.

How to use

The API serves up its own JSON-formatted schema using HTTP:

$ curl https://api.heroku.com/schema  -H "Accept: application/vnd.heroku+json; version=3"
{
  "description": "The platform API empowers developers to automate, extend and combine Heroku with other services.",
  "definitions": {
  ...
  }
}

Please see client libraries mentioned in the introduction for examples of how to consume the schema.