API専用アドレスに移行する

以前の連携システムは、Sursaのメインアドレス、つまりユーザーがブラウザーで開くアドレス（たとえばhttps://app.sursa.com/v1/…）でAPIを呼び出しています。現在、APIには専用のアドレスもあります。クラウドではhttps://api.sursa.com、自社のインストール環境ではhttps://api.<your domain>です。このアドレスは連携システムのために作られています。ロードバランサーの背後でスケールアウトし、API以外は何も提供しません。

移行する必要はありません。メインアドレスは、既存の連携システムのために、終了日もリダイレクトもなく/v1を提供し続けます。API専用アドレスの利点を得たいときに都合のよいタイミングで移行し、新しい連携システムにはすべてAPI専用アドレスを使ってください。

変わらないこと

パス、パラメーター、フィールド、エラーコード、イベント。GET /v1/cardsは、どちらのアドレスでも同じリクエストです。
APIキー。同じkb_とkbsrc_のキーが、同じロール、スコープ、データプロファイルのまま、どちらのアドレスでも使えます。
冪等キー、レート制限、クォータ。どちらのアドレスへのリクエストも、組織の同じクォータに数えられます。
Webhook。配信、署名、シークレットは、呼び出すアドレスには左右されません。
レスポンスのリンク。どのアドレスを呼び出しても、エラーのdoc_urlはこのポータルを指し、リストのページのLinkヘッダーはAPI専用アドレスを指します。

API専用アドレスで異なること

メインアドレス	API専用アドレス
内部向けを含む、Webアプリケーションのすべてのエンドポイント	公開されているAPIリファレンスのエンドポイントだけ。それ以外のパスには、コード`api.not_found`とともに`404`が返ります。
`X-API-Key`または`Authorization`のキー、あるいはブラウザーのセッションCookie	キーまたはOAuthアクセストークン。できれば`Authorization: Bearer`で送信します。Cookieは無視されます。
`GET /auth/me`	`GET /v1/me`。`/auth/`以下のパスは提供されません。
Cookieによる「View as」モード（別のユーザーとして表示）	`admin`ロールのキーで使う`X-View-As`ヘッダー。
1台のサーバー、または固定のサーバー群	ロードバランサーの背後の複数のサーバー。

最後の行が問題になるのは、POST /v1/chatのストリーミングの回答という1つの場合だけです。途切れたストリームがLast-Event-IDから続くのは、回答を書いているサーバー上だけです。連携システムでストリームを再開する場合は、すべての質問にrequest_idを付けてください。そうすれば、別のサーバーでの再試行でも、2つ目の回答ではなく保存済みの回答が返ります。途切れたストリームを再開するを参照してください。

移行の前に

すべての呼び出しが公開されたものか確認する。連携システムが呼び出すパスを一覧にして、それぞれをAPIリファレンスで調べるか、新しいアドレスの仕様と比較してください。

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

公開リファレンスにないパスは、Webアプリケーションのものです。メインアドレスでは引き続き動作しますが、API専用アドレスでは提供されず、その形は公開の約束の対象ではありません。公開されているエンドポイントに置き換えるか、連携システムのその部分をメインアドレスに残し、必要なものをSursaの担当窓口に伝えてください。

認証方法を確認する。連携システムがユーザーのパスワードとセッションCookieでサインインしている場合は、先にAPIキーに切り替えてください。X-API-Keyを送信している場合、Authorization: Bearerへの切り替えは推奨ですが、必須ではありません。

ネットワークを確認する。ファイアウォールとプロキシーで、新しいホスト名への外向きのHTTPSを許可してください。

段階的に移行する

まだ設定項目になっていなければ、ベースURLを連携システムの設定項目にします。

読み取りのリクエストで新しいアドレスを試します。

curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

テスト用のキーとテスト用のコレクションを使って、新しいアドレスに対して連携システムのテストスイートを実行します。
1つのワーカーや1つの環境など、トラフィックの一部を切り替え、ログで404 api.not_found、401、5xxに注意します。すべてのレスポンスにはX-Request-Idが付くので、ログと一緒に保存してください。
残りを切り替えます。数秒で元に戻せるように、しばらくのあいだ古いベースURLを設定に残しておきます。

移行後に確認すること

新しいアドレスのGET /v1/healthが、古いアドレスと同じversionを返すこと。
レスポンスにRateLimitヘッダーがあること。連携システムがX-RateLimit-*に従って速度を落としている場合は、そのままで問題ありません。両方のヘッダーが送信されます。レート制限とクォータを参照してください。
連携システムがブラウザーで動作する場合、CORSのための自社のプロキシーはもう不要です。API専用アドレスは、Cookieなしで任意のオリジンからのリクエストを許可します。