APIの実務の基本(GET/POST/PUT/PATCH/DELETE・JSON・ヘッダー・認証/トークン・レート制限・ページング・タイムアウト・リトライ)

要点

APIは「URL+方法(GET/POST等)+ヘッダー(認証・形式)+本文(JSON)」で頼み、ステータスコードとJSONで答えが返る。認証キーはサーバー側だけに置きブラウザのJSに書かない。レート制限・ページング・タイムアウト・リトライを前提に作る。

外部サービスとの組み込み方の比較(リンク・iframe・API)は 外部サービスの組み込み方の違い(リンク・iframe・script埋め込み・ウィジェット・API)と自サイトCSSが効かない理由。ここは API で連携するときに知っておくこと。

リクエストとレスポンス

リクエスト: 方法 + URL + ヘッダー + (本文)
  POST https://api.example.com/v1/contacts
  Authorization: Bearer <トークン>
  Content-Type: application/json
  {"name": "山田", "email": "..."}

レスポンス: ステータスコード + ヘッダー + 本文(多くはJSON)
  201 Created
  {"id": 123, "status": "ok"}

方法(メソッド)

方法意味何度送っても同じ結果か
GET取得(一覧・詳細)同じ(データは変わらない)
POST新規作成・処理の実行(注文・送信)違う(2回送ると2件できることがある)
PUT丸ごと置き換え同じ
PATCH一部だけ更新多くは同じ
DELETE削除同じ(2回目は「もうない」)

POST の再送は二重登録の原因になる。サービスが重複防止のキー(idempotency key)を用意していれば使う。

ヘッダーと認証

運用で必ず考えること

項目内容
rate limit(レート制限)一定時間の呼び出し回数の上限。超えると 429。アクセスのたびにAPIを呼ばず、結果をキャッシュする
pagination(ページング)一覧は1回で全部返らない。page や cursor で続きを取る。最初のページだけで「全部」と思わない
timeout相手が遅いときに待つ上限。設定しないとサイト表示ごと止まる
retry(再試行)429・500系・タイムアウトは間隔を空けて数回まで再試行(間隔を少しずつ延ばす)。400系(送った内容の誤り)は再試行しても直らない
障害時の表示APIが止まってもページが壊れないように、代わりの表示(「現在表示できません」+リンク)を用意
ログ失敗したリクエストのステータス・時刻・エラー本文を記録(キー・個人情報は伏せる)
仕様変更バージョン(/v1/)と廃止予定の告知を確認

HP制作でのよくある使い道