最終更新日 2020年07月13日(月)

概要

Add-on Partner API は、Heroku がアドオンサービスを呼び出すときに使用されます。これらの例では、Heroku がリクエストを発行し、アドオンが応答を提供します。

一般的なガイドライン

アドオンサービスは、このドキュメントに一覧表示されているすべての呼び出しを実装する必要があります。処理できないリクエストでは、ユーザーへの情報量の多いメッセージを含む 422 応答を返す​べきです。

認証

アドオンマニフェスト​で指定されているアドオン id​ (多くの場合は、アドオン識別子または slug と呼ばれる) と password​ を使用して、すべての呼び出しを HTTP 基本認証で保護するべきです。

べき等性

リクエストは複数回送信される可能性があり (Heroku は少なくとも 1 回の配信のパターンに従う)、エンドポイントはべき等的に応答する必要があります。たとえば、リソースの作成の場合、同じパラメータを含む複数の POST では 1 つのリソースだけがプロビジョニングされる必要があります。

検証

リクエスト本体には、現在ここに記載されていない追加の要素を含めることができ、このようなリクエストは有効として扱う必要があります。

タイムアウト

サービスは、3 秒以内に応答するべきです。現在は、25 秒以内に返す必要があり、そうしないとリクエストが失敗します。この上限は、当社の裁量によって時間の経過と共に、および当社の分析に基づいて短縮されます。

バージョン管理

この API の現在のバージョンはバージョン 3​ です。このドキュメントでは、従来のバージョンについて説明します。

応答本体

すべての応答本体に有効な JSON を含める必要があります。

例外

API でリクエストを満たすことができない場合、それが無効なリクエスト (存在しないプランなど) のためである場合は 4xx の範囲、または API で予期しないエラーが発生している場合は 5xx の範囲の適切な HTTP ステータスコードで応答するようにしてください。エラー応答本体には有効な JSON を含める必要があります。

プロビジョニングおよびプラン変更リクエストに対する 4xx および 5xx 応答の場合は、JSON 応答の message​ プロパティがユーザーに表示されます。その他のすべての応答の場合、および message​ プロパティが使用できない場合は、一般的なエラーメッセージが表示されます。

Platform API

アドオンがプロビジョニングされたら、Platform API​ を使用してアドオンのインストールに関する情報に対してクエリを実行したり、アドオンの環境設定を更新したりすることができます。以前は、この目的のためにアプリ情報 API​ を使用することを推奨しましたが、パートナーは Platform API に移行することをお勧めします。

プロビジョニング

Heroku からアドオンサービスへのプロビジョニングリクエストです。

パラメータ

オプションパラメータ

リクエストの例

POST /heroku/resources HTTP/1.1
Host: addon-slug.herokuapp.com
Authorization: Basic YWRkb24tc2x1ZzpzdXBlci1zZWNyZXQ=
Content-Type: application/json
Accept: application/json

{
  "callback_url": "https://api.heroku.com/vendor/apps/app1234@heroku.com",
  "heroku_id": "app1234@heroku.com",
  "oauth_grant": {
    "code": "01234567-89ab-cdef-0123-456789abcdef",
    "expires_at": "2016-03-03T18:01:31-0800",
    "type": "authorization_code"
  },
  "options": { "foo" : "bar", "baz" : "true" },
  "plan": "basic",
  "region": "amazon-web-services::us-east-1",
  "log_input_url": "https://token:t.01234567-89ab-cdef-0123-456789abcdef@1.us.logplex.io/logs",
  "log_drain_token": "d.01234567-89ab-cdef-0123-456789abcdef"
}

パラメータ

オプションパラメータ

応答の例

HTTP/1.1 202 Accepted

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "message": "Resource has been created and is available!",
  "config": { "MYADDON_URL": "http://myaddon.com/52e82f5d73" }
}

プラン変更

ユーザーがインストールされているアドオンのプラン変更を要求すると、Heroku は API に PUT​ リクエストを送信します。

プラン変更をサポートできない場合は、以下の説明​に従って、ステータスコード 422​ または 503​ で応答し、ユーザーに表示するメッセージを返します。たとえば、ユーザーの現在のプランと要求されたプランの間で変更を行うことができない場合は、説明の message​ を含む 422​ ステータスコードが適切です。ただし、プラン変更が内部の原因で失敗し、ユーザーが後で再試行する必要がある場合は、503​ の方がより適切であることがあります。

パラメータ

リクエストの例

PUT /heroku/resources/:provider_id HTTP/1.1
Host: addon-slug.herokuapp.com
Authorization: Basic YWRkb24tc2x1ZzpzdXBlci1zZWNyZXQ=
Content-Type: application/json
Accept: application/json

{
  "heroku_id": "app1234@heroku.com",
  "plan": "basic"
}

オプションパラメータ

応答の例

HTTP/1.1 200 OK

{
  "message": "Resource has been updated and is available!"
}

プロビジョニング解除

アドオンがユーザーのアカウントから削除されたら、Heroku は API への DELETE​ リクエストを作成します。

リクエストの例

DELETE /heroku/resources/:provider_id HTTP/1.1
Host: addon-slug.herokuapp.com
Authorization: Basic YWRkb24tc2x1ZzpzdXBlci1zZWNyZXQ=
Content-Type: application/json
Accept: application/json

応答の例

HTTP/1.1 204 No Content