§24-01
API key 管理 (生成/失効)
API キーを発行・失効し、秘密は一度だけ表示する。
開発者が自分でキーを作り、漏えい時にすぐ無効化できる。外部連携や API を提供するサービスの開発者設定に必要になる。
実装のポイントシークレットは発行直後に一度だけ全文を表示し、以降はプレフィックスのみ保持する。削除は即時失効なので確認ダイアログを挟む。
- 状態管理
§24
開発者向け公開機能
Developer
- Patterns
- 12
- Demos
- 12
§24-02
OAuth app 管理
外部連携アプリの登録と認証情報を管理する。
開発者が自分のアプリから API に接続する認証情報を自力で発行し管理する。連携を増やしたい開発者向けサービスで使う。
実装のポイントclient_secret は作成時に一度だけ表示して再発行で置き換え、redirect URI は完全一致で登録させる。
- 状態管理
§24-03
Webhook 設定 + テスト送信
Webhook の URL を登録しテスト送信で確認する。
外部システムとの連携を、実際の通知を受け取りながら設定できる。連携が動かないときの原因調査にも使える。
実装のポイントテスト送信はサーバーから実際に ping を送り、ステータスコードと応答時間を表示する。署名シークレットで受信側が検証できるようにする。
- フォーム
- 非同期
§24-04
Webhook ログ / 再配信
Webhook の配信履歴を一覧し、再送できる。
外部へ送った通知が届いたかを開発者が確認し、失敗分をやり直せる。連携先の障害で取りこぼした通知を手元で復旧できる安心感を与える。
実装のポイント失敗した配信は指数バックオフで自動再試行し、手動の再配信ボタンも残す。リクエストとレスポンスの本文を展開して確認できるようにする。
- 状態管理
§24-05
API playground / cURL builder
API をブラウザから呼び出し結果を確かめられる。
コードを書く前に動作とレスポンスの形を試せる。開発者向けドキュメントに添えて、導入の最初の一歩を軽くする。
実装のポイント入力したメソッド・パス・ヘッダーから cURL コマンドを同時に生成してコピーできるようにし、API キーは画面上で伏せる。
- モック
- 非同期
§24-06
API ドキュメント (Algolia 検索付)
一覧・説明・コード例の 3 ペインで API を解説する。
開発者が目的のエンドポイントを探し、すぐに試せる形で情報を得る。説明とコード例を往復する手間を減らす。
実装のポイント左にエンドポイント一覧、中央に説明、右にコード例の 3 ペインにし、狭い画面では一覧をドロワーへ畳む。検索は Cmd+K で開く。
- キーボード操作
§24-07
Rate limit indicator
API の残り呼び出し回数を表示する。
上限に達する前に利用者が気付き、処理を調整できる。従量制や厳しい上限のある API を提供するサービスで使う。
実装のポイント残量は X-RateLimit-Remaining と Reset ヘッダーから算出し、閾値を超えたら色と文言で警告する。バーには role=progressbar と aria-valuenow を付ける。
- 状態管理
残り 4 件のパターンEmbed code generator / SDK / CLI download / Changelog (devs 向け) …
§24-09
Embed code generator
埋め込み用のタグを生成してコピーできる。
自分のサイトにウィジェットを貼りたい人が、設定を選ぶだけでコードを手に入れられる。外部サイトへの配布を広げたい機能に向く。
実装のポイント幅・テーマなどのオプションを変更するとコードが即時更新される生成 UI にし、コピー後は「コピーしました」を aria-live で通知する。
- ブラウザ API
§24-10
SDK / CLI download
OS や言語ごとに SDK や CLI の入手手順を示す。
開発者が自分の環境に合う導入手順にすぐ辿り着けるようにする。複数の環境を一つの手順に混ぜて混乱させない。
実装のポイントアクセス元の OS やパッケージマネージャを推定して初期タブを決め、コマンドには個別のコピーボタンを付ける。
- 状態管理
§24-11
Changelog (devs 向け)
開発者向けの変更履歴で破壊的変更を強調する。
API 利用者がアップデートの影響を素早く判断し、対応が必要な変更を見逃さない。SDK や公開 API を提供するサービスで使う。
実装のポイント破壊的変更は専用ラベルで強調し、移行手順へのリンクと影響を受ける API バージョンを添える。RSS などの購読手段も用意する。
- 状態管理
§24-12
環境切替 (test / live)
テスト環境と本番環境をダッシュボード上で切り替える。
本番に影響を与えずに動作を試せる環境を用意し、どちらを見ているかを常に明示する。決済や外部連携のように、誤操作が実害につながる機能で必須。
実装のポイントtest と live でデータもキーも完全に分離し、test 中は画面全体に色付きの帯を出して取り違えを防ぐ。切替はサーバー側のキー選択と連動させる。
- 状態管理