Migrating to Platform API for Partners

Last updated October 03, 2022

If you your add-on uses our Legacy Add-on Partner App Info API, follow this guide to replace all calls to the legacy API with calls to Platform API for Partners. We will be removing support for the legacy API no later than July 3, 2023. If there are any changes to the deprecation timeline, we’ll update this article and announce it via the Heroku Changelog accordingly. For more information on the Add-on Partner App Info API end of life, see our FAQ article.

Your add-on must implement Add-on Partner API V3 before you can replace your calls to the legacy App Info API with calls to our current Platform API. If you built your add-on before May 2018 and haven’t migrated previously, your add-on integration still uses our legacy Add-on Partner API V1. You will need to follow this guide to migrate your add-on to our current integration API before attempting the endpoint replacements described here.

The Platform API for Partners allows add-ons to access a subset of our main Platform API via scoped OAuth tokens. This allows add-on partners to integrate more deeply and securely into the Heroku ecosystem, and fully replaces our legacy Add-on Partner App Info API. Moving forward, it will be the only way for your add-on services to update add-on config vars and retrieve app, collaborator, attachment and other add-on resource specific metadata.

Our legacy App Info API provides three endpoints of interest for add-on providers:

  • Get All Apps.
  • Get App Info.
  • Update Config Vars.

Get All Apps endpoint replacement

The legacy Get All Apps endpoint allows you get a list of apps that have installed your add-on.

Example Legacy Get All Apps request to be replaced

$ curl https://logcapture-staging:6349E6585913eD9a1@api.heroku.com/vendor/apps

[
  {
    "callback_url": "https://api.heroku.com/vendor/apps/fc045862-3954-4869-80d3-0a69063f995f",
    "heroku_id": "app888888888@heroku.com",
    "name": "test-app-1",
    "resource": {
      "uuid": "fc045862-3954-4869-80d3-0a69063f995f",
      "name": "logcapture-staging-silhouetted-45667"
    },
    "plan": "test",
    "provider_id": "provider_id_12345"
  },
  {
    "callback_url": "https://api.heroku.com/vendor/apps/e5d0dc92-0e7d-4720-af67-0ec40198421f",
    "heroku_id": "app878787878@heroku.com",
    "name": "test-app-2",
    "resource": {
      "uuid": "e5d0dc92-0e7d-4720-af67-0ec40198421f",
      "name": "logcapture-staging-concave-99081"
    },
    "plan": "test",
    "provider_id": "provider_id_67890"
  }
]

Platform API for Partners can’t provide an endpoint where you can fetch a list of applications that have your add-on installed due to the fact that authentication is token based and the tokens are scoped to a specific resource for which they were granted. To overcome this limitation, we have added a new Apps endpoint to the Add-ons API v3 that can be used for this purpose.

Add-ons API v3 is our public API powering your company users’ interactions within the Partner Portal, but also enabling add-on providers to access and update that information programmatically.

In order to use the Apps endpoint you will need to authenticate against Add-ons API v3 with an authorization token belonging to one of the registered company users. Heroku users can generate temporary or long-lived authorizations through Dashboard (User menu → Account Settings → Applications → Authorizations) or Heroku CLI tool.

Example long-lived authorization creation

$ heroku authorizations:create -d "Add-ons API v3 access token"
Creating OAuth Authorization... done
Client:      <none>
ID:          e844f998-4852-4176-bd35-9d5b74e18f46
Description: Add-ons API v3 access token
Scope:       global
Token:       0b6cbe5f-9d1e-4277-b842-dd1361b60909

Use the generated access token as a Bearer token on the Authorization header when making the request to Add-ons API v3.

Example Apps request to Add-ons API V3

$ curl https://addons.heroku.com/api/v3/addons/logcapture-staging/apps \
-H "Authorization: Bearer 0b6cbe5f-9d1e-4277-b842-dd1361b60909" \
-H "Accept: application/json"

[
  {
    "callback_url": "https://api.heroku.com/addons/fc045862-3954-4869-80d3-0a69063f995f",
    "id": "95c71f9b-9068-4829-b3b3-6e0472db7a04",
    "name": "test-app-1",
    "resource": {
      "uuid": "fc045862-3954-4869-80d3-0a69063f995f",
      "name": "logcapture-staging-silhouetted-45667"
    },
    "plan": "test",
    "provider_id": "fc045862-3954-4869-80d3-0a69063f995f"
  },
  {
    "callback_url": "https://api.heroku.com/addons/e5d0dc92-0e7d-4720-af67-0ec40198421f",
    "id": "72657576-cfa5-4130-9d99-92e440549168",
    "name": "test-app-2",
    "resource": {
      "uuid": "e5d0dc92-0e7d-4720-af67-0ec40198421f",
      "name": "logcapture-staging-concave-99081"
    },
    "plan": "test",
    "provider_id": "provider_id_67890"
  }
]

Responses from both the legacy API and Add-ons API V3 share a common pattern, but there are some fundamental differences to keep into account:

  • heroku_id was a legacy app identifier, now deprecated and has been removed in favor of the current id. The new identifier can be used to fetch detailed app information as described in the next section.
  • callback_url was kept for compatibility reasons, but the URI now points to the Add-on Info endpoint in Platform API instead of the legacy API. It’s the same value sent with the initial provisioning request.
  • provider_id was kept for add-on provider reference, but it’s no longer used as the identifier on requests made to your Add-on Partner API integration endpoints. It’s the value associated to the id attribute you set in the response to the initial provisioning request.

Result Pagination

Results larger than 4,000 will be paginated. Pagination information is passed via the Link HTTP header. Use those URIs to navigate the pagination rather than constructing them in your client code.

Example pagination header

Link: <https://addons.heroku.com/api/v3/addons/logcapture-staging/apps?offset=0>; rel="prev", <https://addons.heroku.com/api/v3/addons/logcapture-staging/apps?offset=8000>; rel="next"

The possible rel values within that header are:

  • next: Shows the URL of the immediate next page of results.
  • prev: Shows the URL of the immediate previous page of results.

Get App Info endpoint replacement

If your add-on service implementation uses the Legacy Add-on Partner App Info API to obtain detailed information about an app by means of the Get App Info endpoint, replace those calls with requests to the App Info endpoint from Platform API.

Example Legacy Get App Info request to be replaced

$ curl https://logcapture-staging:6349E6585913eD9a1@api.heroku.com/vendor/apps/provider_id_12345

{
  "callback_url": "https://api.heroku.com/vendor/apps/fc045862-3954-4869-80d3-0a69063f995f",
  "config": {
    "LOGCAPTURE_STAGING_API_KEY": "BiB5GNfw+g3P0IUR8bJr1fKY",
    "LOGCAPTURE_STAGING_URL": "https://logcapture-staging.herokuapp.com/kR2Qvn8gELmdZwZU"
  },
  "domains": [
    "test-app-1.herokuapp.com"
  ],
  "id": "app888888888@heroku.com",
  "name": "test-app-1",
  "owner_email": "developer@logcapture.com",
  "owner": {
    "uuid": "a3bcc594-cd28-4517-ac3a-ab23aa9b6841",
    "email": "developer@logcapture.com"
  },
  "region": "amazon-web-services::us-east-1",
  "resource": {
    "uuid": "fc045862-3954-4869-80d3-0a69063f995f",
    "name": "logcapture-staging-silhouetted-45667"
  },
  "plan": "test",
  "logplex_token": "t.61ebeb54-deba-438e-90a6-16ce6784c338"
}

Notice that when replacing the legacy App Info endpoint with the App Info endpoint from Platform API, the JSON response won’t include related entities like resource and config vars as there are specific endpoints to retrieve that info. You can see a list of available endpoints in the Platform API for Partners article.

Example App Info request from Platform API

$ curl https://api.heroku.com/apps/95c71f9b-9068-4829-b3b3-6e0472db7a04 \
-H "Authorization: Bearer 9ebed010-233d-4de3-9f2f-fdfeddddd9c7" \
-H "Accept: application/vnd.heroku+json; version=3"

[
  {
    "acm": false,
    "archived_at": null,
    "buildpack_provided_description": null,
    "build_stack": {
      "id": "3bcd644c-3108-4c40-8969-2aa29947d1c6",
      "name": "heroku-18"
    },
    "created_at": "2020-06-11T17:23:00Z",
    "id": "95c71f9b-9068-4829-b3b3-6e0472db7a04",
    "git_url": "https://git.heroku.com/test-app-1.git",
    "maintenance": false,
    "name": "test-app-1",
    "owner": {
      "uuid": "a3bcc594-cd28-4517-ac3a-ab23aa9b6841",
      "email": "developer@logcapture.com"
    },
    "region": {
      "id": "8271a929-df76-4021-855f-feb83fee000e",
      "name": "us"
    },
    "organization": null,
    "team": null,
    "space": null,
    "internal_routing": null,
    "released_at": "2020-11-10T20:53:00Z",
    "repo_size": null,
    "slug_size": null,
    "stack": {
      "id": "3bcd644c-3108-4c40-8969-2aa29947d1c6",
      "name": "heroku-18"
    },
    "updated_at": "2021-09-07T06:11:28Z",
    "web_url": "https://test-app-1.herokuapp.com/"
  }
]

Update Config Vars endpoint replacement

Update Config Vars endpoint from the Legacy Add-on Partner App Info API allows you to set or remove config var values controlled by your add-on service. Requests sent to that endpoint should be replaced by calls to the Add-on Config Update endpoint from the Platform API for Partners.

Example Legacy Update Config Vars request to be replaced

$ curl -X PUT https://logcapture-staging:6349E6585913eD9a1@api.heroku.com/vendor/apps/95c71f9b-9068-4829-b3b3-6e0472db7a04 \
-H 'Content-Type: application/json'
-d '{"config":{"LOGCAPTURE_STAGING_URL":"https://logcapture-staging.herokuapp.com/Hgp35ph6YLeaGnPz"}}'

Notice that the JSON payload for the old endpoint consisted of an object containing one single config key with an object value where the keys are the config var names to update and the values contain the literal value to be assigned. For the new endpoint, the JSON payload consists, similarly, of an object with a single config key, However, its value is an array of objects, each of which describes a single config var to update and contains two keys: name and value, whose values are the name of the config var to update and the new value to set respectively.

Example Add-on Config Update request

$ curl -X PATCH https://api.heroku.com/addons/fc045862-3954-4869-80d3-0a69063f995f/config \
-H "Authorization: Bearer 9ebed010-233d-4de3-9f2f-fdfeddddd9c7" \
-H "Content-Type: application/json"
-H "Accept: application/vnd.heroku+json; version=3"
-d '{"config":[{"name":"LOGCAPTURE_STAGING_URL","value":"https://logcapture-staging.herokuapp.com/Hgp35ph6YLeaGnPz"}]}'

[
  {
    "name": "API_KEY",
    "value": "BiB5GNfw+g3P0IUR8bJr1fKY",
  },
  {
    "name": "URL",
    "value": "https://logcapture-staging.herokuapp.com/Hgp35ph6YLeaGnPz"
  }
]

Feedback

Log in to submit feedback.