Optifora の API のしくみ
このページでは API の形を説明します。本人性をどう証明するか、版をどう進めるか、リクエストがどの制限の内側にとどまるか、エラーがどう見えるか、そして外部とどのようにデータを交換するかです。
本製品は開発中で、API の面はまだ整備の途上にあります。端点の参照文書は別途公開します。このページにはアドレスも呼び出し例も載せず、しくみだけを説明しています。
認証
すべてのリクエストは、人か登録済みのアプリケーションのいずれかに属します。本人性のないリクエストが保護された端点に届いた場合は、未認証として返されます。
- Bearer トークンアクセストークンはリクエストの authorization ヘッダーで送られます。署名されており、そのリクエストが誰のものかだけを示します。
- 有効期間は短くアクセストークンは分単位の期間で失効します。長さは配備時の設定で、既定は 30 分です。
- 更新とローテーションセッションはリフレッシュトークンで延長し、延長のたびに新しい組を発行します。使用済みのリフレッシュトークンが再度提示された場合、その利用者のセッションはすべて失効します。
- 権限はトークンに焼き付けませんトークンが運ぶのは本人性だけです。誰が何を参照できるかは、リクエストのたびにデータベースへ問い合わせます。取り消された権限は、手元のトークンが切れるより先に効かなくなります。
- 連携用キー登録済みのアプリケーションは、それぞれ固有のキーで接続します。平文の値は作成時に一度だけ表示され、保存されるのはそのダイジェストと、キーを識別するための秘密でない接頭辞だけです。
- アクセスを許可するのは組織ですどれほど広く使われているアプリケーションであっても、組織が記録した許可がなければ 1 行も参照できません。許可には日付と範囲があり、いつでも取り消せます。
版管理
- 版は経路の中にあります端点は版の接頭辞の下で公開します。現在の面は第 1 版です。
- 破壊的な変更は新しい経路を開きます既存の端点の取り決めをその場で壊すことはしません。互換性のない変更は新しい版の経路で公開し、古い経路は動き続けます。
- 文書は自身の版を明示します参照文書には、生成元の版番号が記されています。どの版を読んでいるかは、文書自身が答えます。
環境と制限
参照文書では本番と開発用ローカルの 2 つの環境を定めています。基点アドレスはキーとともに連携先へ個別にお渡しし、このページでは公開していません。
- 生存確認と受入準備は別々に測ります一方の端点はプロセスが生きていることを示し、もう一方はデータベースへ実際に問い合わせて到達できることを確かめます。通信を流してよいかを決めるのは後者だけです。
- ブラウザーのオリジンは一覧で限定しますオリジンをまたぐリクエストは、あらかじめ申告されたオリジンからのみ受け付けます。一覧が空の間は、ブラウザーからのオリジンをまたぐリクエストは拒否されます。
- 本文の上限リクエスト本文は 5 メガバイトを超えられません。大量のデータは 1 回のリクエストではなく、独自の状態記録を持つ一括転送ジョブとして扱います。
- 秘密は記録に書きませんサーバーの記録には、authorization ヘッダー、クッキー、パスワード、国民識別番号のいずれも残しません。
流量制限
制限はアドレスごと、1 分ごとです。既定は毎分 120 リクエストで、配備時に設定します。残り回数はすべての応答のヘッダーで通知されます。
| 応答ヘッダー | 示す内容 |
|---|---|
| x-ratelimit-limit | 時間枠の中で許される総回数です。 |
| x-ratelimit-remaining | この時間枠で残っている回数です。 |
| x-ratelimit-reset | 許容回数が回復するまでの秒数です。 |
| retry-after | 再試行までの秒数。リクエストを拒否した応答にのみ含まれます。 |
制限を超えるとリクエストは拒否され、応答には待つべき秒数が示されます。再試行はその時間の経過後に行い、すぐには行いません。
エラーの形式
エラーはすべて同じ包みで返ります。機械が分岐に使う短いコード欄と、人が読むための説明欄です。
- errorクライアントが分岐の判断に使う短いコードです。
- message何が起きたかの説明です。
| 状態 | コード欄 | 意味 |
|---|---|---|
| 400 | Bad Request | リクエストがスキーマに合致していません。説明文に、欠けている項目または不正な項目の名前が示されます。 |
| 401 | unauthenticated | 有効な本人性がありません。トークンが送られていないか、失効しているか、検証できませんでした。 |
| 404 | Not Found | その端点が存在しないか、該当する記録がありません。 |
| 429 | Too Many Requests | 流量制限を超えました。応答には、どれだけ待つべきかが示されます。 |
| 5xx | internal_error | 想定外の障害です。詳細はクライアントには渡さず、サーバーの記録に書き出します。 |
ページ送り
一覧を返す端点は同じ 2 つの引数を取り、同じ計数を返します。そのため、ページ送りの処理を端点ごとに書き直す必要はありません。
- limit1 ページに含める記録の数です。最小 1、最大 200、未指定の場合は 50 です。
- offset読み飛ばす記録の数です。0 から始まります。
- total絞り込み条件に合致する記録の総数です。
- countこの応答が実際に含む記録の数です。
応答は、使用した limit と offset もそのまま返します。クライアントは自分の位置を推測せず、応答から読み取ります。
データ交換とウェブフック
交換の方式は別製品ではなく設定です。登録済みのアプリケーションは、自身がどの方式で動くかを自分の記録に持っています。
| 方式 | 意味 |
|---|---|
| 片方向 — 送出 | Optifora がデータを公開し、相手側がそれを読むか、イベントを購読します。 |
| 片方向 — 受入 | 相手側がデータを送り込み、Optifora が検証して書き込みます。 |
| 双方向 | 双方が書き込みます。競合時の規則はあらかじめ定めます。 |
| ハンドシェイク | 受け渡しのたびにセッションを開きます。申し出、検証、承認、転送、受領証の順です。受領証は双方に残ります。 |
- イベントは外へ送り出しますウェブフックは、登録済みのアプリケーションが申告した折り返し先アドレスへイベントを送ります。届けられなかったイベントは待ち行列に残して再送し、黙って捨てることはありません。
- 同じリクエストが二重に書き込むことはありません書き込みのリクエストには冪等キーを付けます。同じキーの 2 回目のリクエストで、2 つ目の記録が作られることはありません。
- 呼び出しはすべて計測します誰が、いつ、どの範囲で、どのような結果で呼び出したかをすべて記録します。同じ記録が、不具合の調査にも「このデータを誰が取り出したか」という問いにも答えます。
- 自社のアプリも同じ入口を使います特権的な別経路はありません。私たち自身の連携が、外部の開発者が出会う面そのものの証拠です。
交換層のデータモデルは整っていますが、その端点はまだ公開していません。公開の際には、この節から参照文書の該当項目にリンクします。
参照文書
参照文書は手書きせず、端点のスキーマから生成します。各端点がスキーマを渡すたびに文書はひとりでに埋まるため、文書と実際の挙動が食い違うことはありません。
- 現時点 : 準備中スキーマはモジュール単位で移行を進めています。文書の公開前には、すべての端点の要求と応答がその中で確認できるようになります。
- 公開する形式は 2 つ機械が読む OpenAPI 文書と、その同じ文書から生成されブラウザーで閲覧できる参照ページです。
- アクセスは段階制です概要は誰でも参照できます。完全な参照文書は、登録済みの連携先に発行する文書用トークンの内側に置く場合があります。本番用のキーと折り返し先のアドレスは、そもそも文書の話ではなくアプリケーションの登録記録に属します。
- アドレスの標準参照文書は 2 つ公開し、アドレスは固定です。client-api.optifora.com/docs は公開、admin-api.optifora.com/docs は認可が必要で外部には閉じています。いずれも本日時点では稼働していません。稼働しだい、この節にリンクを追加します。
連携の計画がすでに具体的であれば、お問い合わせページからご連絡ください。面が開いた際に、いち早くお知らせします。