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)を用意していれば使う。
ヘッダーと認証
Content-Type: application/json(送る本文の形式)、Accept(受け取りたい形式)。- 認証の主な方式: APIキー(ヘッダーに入れる)、トークン(
Authorization: Bearer ...)、OAuth(ユーザーの許可を得てトークンを発行)。 - 秘密のキー・トークンはサーバー側だけで使う。ブラウザのJavaScriptやHTMLに書くと誰でも見られる。URLのクエリにキーを入れるとログや履歴に残る。
- 公開してよい「公開用キー」(ドメイン制限付きの地図キーなど)と、秘密のキーを区別する。
- knowledge・Git・AIへの依頼文に実際のキーを書かない(認証情報(パスワード・秘密鍵・APIキー・トークン)はknowledgeに保存しない、Gitの安全な使い方(commit前にstatus/diff・秘密情報をcommitしない・.gitignore・消しても履歴に残る))。
- トークンには期限がある。期限切れで急に 401 になる(APIエラーの見方(200系・400・401・403・404・422・429・500系でどこを疑うか))。
運用で必ず考えること
| 項目 | 内容 |
|---|---|
| rate limit(レート制限) | 一定時間の呼び出し回数の上限。超えると 429。アクセスのたびにAPIを呼ばず、結果をキャッシュする |
| pagination(ページング) | 一覧は1回で全部返らない。page や cursor で続きを取る。最初のページだけで「全部」と思わない |
| timeout | 相手が遅いときに待つ上限。設定しないとサイト表示ごと止まる |
| retry(再試行) | 429・500系・タイムアウトは間隔を空けて数回まで再試行(間隔を少しずつ延ばす)。400系(送った内容の誤り)は再試行しても直らない |
| 障害時の表示 | APIが止まってもページが壊れないように、代わりの表示(「現在表示できません」+リンク)を用意 |
| ログ | 失敗したリクエストのステータス・時刻・エラー本文を記録(キー・個人情報は伏せる) |
| 仕様変更 | バージョン(/v1/)と廃止予定の告知を確認 |
HP制作でのよくある使い道
- フォーム送信内容を外部のCRM・スプレッドシートへ送る。
- 在庫・予約枠・お知らせを外部サービスから取得して表示。
- Webhook で外部サービスから通知を受ける(Webhookの基本(APIとの違い・受信URL・署名確認・再送・重複・失敗時))。
- ブラウザから直接呼ぶと CORS で止まることがある(CORSエラーの基本(別オリジン・ブラウザの制限・Access-Control-Allow-Origin・iframeとは別問題))。