Deep-dive on the Next Gen Platform. Join the Webinar!

Skip Navigation
Show nav
Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
    • .NET
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
Hide categories

Categories

  • Heroku Architecture
    • Compute (Dynos)
      • Dyno Management
      • Dyno Concepts
      • Dyno Behavior
      • Dyno Reference
      • Dyno Troubleshooting
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Developer Tools
    • Command Line
    • Heroku VS Code Extension
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery & Integration (Heroku Flow)
    • Continuous Integration
  • Language Support
    • Node.js
      • Working with Node.js
      • Troubleshooting Node.js Apps
      • Node.js Behavior in Heroku
    • Ruby
      • Rails Support
      • Working with Bundler
      • Working with Ruby
      • Ruby Behavior in Heroku
      • Troubleshooting Ruby Apps
    • Python
      • Working with Python
      • Background Jobs in Python
      • Python Behavior in Heroku
      • Working with Django
    • Java
      • Java Behavior in Heroku
      • Working with Java
      • Working with Maven
      • Working with Spring Boot
      • Troubleshooting Java Apps
    • PHP
      • PHP Behavior in Heroku
      • Working with PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
    • .NET
      • Working with .NET
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
      • Migrating to Heroku Postgres
    • Heroku Key-Value Store
    • Apache Kafka on Heroku
    • Other Data Stores
  • AI
    • Working with AI
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
      • Single Sign-on (SSO)
    • Private Spaces
      • Infrastructure Networking
    • Compliance
  • Heroku Enterprise
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Extending Heroku
  • Platform API
  • API Compatibility Policy

API Compatibility Policy

English — 日本語に切り替える

Last updated April 03, 2023

Table of Contents

  • Versions and resource stability
  • Types of changes
  • Selecting API version

This article describes Heroku’s commitment to compatibility for services built on the Platform API. It also describes how we will introduce changes to the API and how those changes are communicated.

Versions and resource stability

V3 is the current and only supported version of the Platform API.

Within any given version of the API, any given resource (eg. /apps, /account or /apps/:id/addons) has a specified level of stability. The stability of a resource is specified in the JSON Schema stability property. It’s also displayed in the Platform API reference document.

The stability of a resource specifies what changes (if any) Heroku will make to the resource and how changes will be communicated. The possible types of changes are detailed below. All changes are communicated in the Heroku Changelog.

There are three levels of stability: prototype, development, and production.

Prototype

A prototype resource is experimental and major changes are likely. In time, a prototype resource may or may not advance to production.

  • Compatible and emergency changes may be made with no advance notice
  • Disruptive changes may be made with one week notice
  • Deprecated resources will remain available for at least one month after deprecation

Development

A Development resource is a work-in-progress, but major changes should be infrequent. Development resources should advance to production stability in time.

  • Compatible and emergency changes may be made with no advance notice
  • Disruptive changes may be made with one month notice
  • Deprecated resources will remain available for at least six months after deprecation

Production

A production resources is complete and major changes will no longer occur.

  • Compatible and emergency changes may be made with no advance notice
  • Disruptive changes may not occur, instead a new major version is developed
  • Deprecated resources will remain available for at least twelve months after deprecation

Deprecation

Deprecated resources have a deprecated_at date property in the JSON Schema which is also displayed in the API Reference documentation. Deprecated resources will keep working for at least as long after deprecation as mandated by their stability: 1 month for prototype resources, 6 month for development resources and 12 months for production resources. Deprecated resources will not change stability.

Once a resource has been completely deactivated, it will return HTTP 410 for all requests.

Types of changes

Compatible change

Small in scope and unlikely to break or change semantics of existing methods.

  • Add resources, methods and attributes
  • Change documentation
  • Change undocumented behavior

Disruptive change

May have larger impact and effort will be made to provide migration paths as needed.

  • Change semantics of existing methods
  • Remove resources, methods and attributes

Emergency change

May have larger impact, but are unavoidable due to legal compliance, security vulnerabilities or violation of specification.

Selecting API version

To use the current v3 version of the API, pass this header in requests: Accept: application/vnd.heroku+json; version=3.

A particular resource will only ever have one stability for a particular version of the API. That means that if the /apps endpoint is of production stability in v3, there is no “prototype” work happening for /apps in v3.

If Heroku wanted to introduce breaking changes to the /apps endpoint after it had reached production stability in v3, that work would happen in a new API version, eg. v4. No such version currently exists, but if it did, you could access it by passing the correct header: Accept: application/vnd.heroku+json; version=4.

A future API version may not support all resources available in current API versions, it might support new ones, or resources may be re-organized or re-named. A future v4 API may thus have an /apps resource, but no /account resource (requests to that would return HTTP 404). To see what resources are supported for a particular API version, you can always inspect its published JSON Schema:

$ curl https://api.heroku.com/schema  -H "Accept: application/vnd.heroku+json; version=4"

Keep reading

  • Platform API

Feedback

Log in to submit feedback.

Setting Up Apps Using the Platform API app.json Schema

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure
  • .NET

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
  • © 2025 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners. Salesforce Tower, 415 Mission Street, 3rd Floor, San Francisco, CA 94105, United States
  • heroku.com
  • Legal
  • Terms of Service
  • Privacy Information
  • Responsible Disclosure
  • Trust
  • Contact
  • Cookie Preferences
  • Your Privacy Choices