本文へスキップ
Sursa Developers

APIアドレスと環境

Sursa APIには、ユーザーがブラウザーでSursaを開くアドレスとは別の、専用のアドレスがあります。パスはすべて/v1で始まります。

Sursaの稼働場所APIアドレスこのポータル
Sursaのクラウドhttps://api.sursa.comhttps://developers.sursa.com
自社のインストール環境管理者が設定したhttps://api.<your domain>APIアドレスの/developers/
API専用アドレスのない自社のインストール環境インストール環境のメインアドレスメインアドレスの/developers/

APIアドレスはAPIだけを提供します。サインインページも、Cookieも、Webインターフェースもありません。リクエストはすべてAPIキーまたはOAuthアクセストークンで認証されます。アドレスはロードバランサーの背後にある複数のサーバーで提供されることがありますが、連携システムがサーバーの数を知る必要はありません。

メインアドレス（たとえばhttps://app.sursa.com/v1）でAPIを呼び出している連携システムは、引き続き動作します。いくつかの違いと段階的な移行の手順は、API専用アドレスに移行するを参照してください。

ベースURL

同じコードがどの環境でも動くように、すべてのリクエストを設定にある1つのベースURLから組み立ててください。

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

HTTPSだけを使い、送信するリクエストのログにキーを残さないでください。

バージョンと仕様

GET /v1/healthは、そのアドレスが稼働しているかどうかを示し、そのアドレスで動作しているSursaのバージョンを返します。キーなしで応答するので、モニタリングに使えます。

curl https://api.sursa.com/v1/health
{"ok": true, "version": "v1.4.0"}

これはSursaのリリースのバージョンで、APIのバージョンではありません。APIのバージョンは、仕様のinfo.versionです。APIのOpenAPI 3.1仕様は、同じアドレスで認証なしに公開されています。

パス内容
GET /openapi.json公開仕様。serversにこのアドレスが入っています。
GET /v1/openapi-public.json同じ仕様。ETagとIf-None-Matchに対応しています。

クライアントの生成、PostmanなどのツールへのAPIのインポート、連携システムが想定したバージョンの操作だけを使っているかのCIでの確認に使ってください。このポータルのAPIリファレンスも同じファイルから作られています。

テスト

Sursaには独立したテストモードはありません。キーを使ったリクエストは、すべてその組織の実際のデータに対して実行されます。安全に開発とテストを行うには：

  • 開発用に別のキーを作成し、作業に必要な最小限のロールとスコープを付与します。
  • 自分のチームだけが参照できる専用のコレクション（たとえばsandbox）に書き込み、作業が終わったら削除します。
  • 自社にテスト用のSursaの組織やインストール環境が別にある場合は、ベースURLとキーをそちらに向けます。コードの他の部分は変わりません。
  • 最初から再試行を安全にしておきます。すべてのPOSTとPATCHでIdempotency-Keyを送信してください。

APIリファレンスの各エンドポイントのページにある試してみるコンソールは、貼り付けたキーを使って実際のリクエストを送信します。キーはブラウザーのタブのメモリにだけ保持され、APIアドレスにだけ送信されます。

ネットワークの要件

  • 自社のサーバーからAPIアドレスへの外向きのHTTPS（ポート443）。
  • ネットワークで可能であれば、ファイアウォールのルールでは固定のIPアドレスではなくホスト名を許可してください。処理能力の増強に伴って、アドレスの背後のサーバーは変わることがあります。
  • ブラウザーアプリケーションはAPIを直接呼び出せます。レスポンスは、Cookieなしで任意のオリジンを許可します（Access-Control-Allow-Origin: *）。ブラウザーで使うキーは、そのブラウザーのユーザーに見えることに注意してください。