変更要約: 初版
2.1REST APIリクエストの構築
API docsを読み解いて目的のタスクを実現するREST APIリクエストの組み立て——HTTPメソッド（GET/POST/PUT/PATCH/DELETE）とエンドポイント（URL）、Content-Type/Accept/Authorizationなどのヘッダ、クエリパラメータ、JSONのリクエストボディ——と、Basic認証・APIキー・Bearerトークン（OAuth）という認証方式を、「このdocsの要求どおりにリクエストを組めているか」という診断として学びます。
API連携は「メソッドの一覧を暗記する」作業ではなく、API docsを読み解いて、目的のタスクを実現する正しいHTTPリクエストを組み立てる作業です。同じ「デバイス一覧を取得する」でも、エンドポイントのURL・必須ヘッダ・認証方式・必要なパラメータはAPIごとに異なり、そのどれか1つを取り違えるだけでリクエストは失敗します。この節では、リクエストの構成要素と代表的な認証方式（Basic・APIキー・Bearerトークン）を押さえ、「docsの要求と自分のリクエストがどこでずれているか」を突き止める目を養います。
2.1.1リクエストの構成要素
- HTTPメソッドが操作の種類を表す：GET（取得・副作用なし）／POST（作成）／PUT（リソース全体の置換）／PATCH（部分更新）／DELETE（削除）。docsが「リソースを新規作成」と書いていればPOST、「既存の一部フィールドだけ変更」ならPATCHというように、やりたいことからメソッドを選ぶ。
- エンドポイント（URL）がリソースの所在を示し、末尾やクエリで対象を絞る。例：
GET https://api.example.com/v1/devices?limit=50。クエリパラメータ（?limit=50&offset=0）は絞り込み・ページングに、リクエストボディ（多くはJSON）はPOST/PUT/PATCHで送るデータ本体に使う。GETは通常ボディを持たない。 - ヘッダがリクエストのメタ情報を運ぶ：送るボディの形式を宣言する
Content-Type: application/json、欲しい応答形式を伝えるAccept: application/json、そして認証情報を載せるAuthorizationが代表格。JSONボディを送るのにContent-Typeを付け忘れると、サーバが本文を解釈できず400 Bad Requestや415になりやすい。
2.1.2認証方式
- Basic認証＝
ユーザ名:パスワードをbase64エンコードしてAuthorization: Basic <base64>で送る。実装は単純だがbase64は暗号化ではなく容易に復号できるため、必ずHTTPS（TLS）上で使う。base64を「暗号化された安全な値」と誤解しないこと。 - APIキー＝発行された秘密の文字列を、docsが指定する場所——ヘッダ（例：
X-Api-Key: <key>やAuthorization）かクエリパラメータ（例：?api_key=<key>）——に載せる。docsが指定した場所と名前に厳密に従うのが肝で、ヘッダ指定なのにクエリに置く／キー名を綴り間違える、が典型的な失敗。 - Bearerトークン＝先に認証してアクセストークンを得（OAuthが代表）、以後は
Authorization: Bearer <token>で送る。トークンには有効期限があり、切れれば401になるため再取得（リフレッシュ）が要る。DevNet系の多くのCisco API（Catalyst Center等）はこのトークン方式で、まずトークン発行エンドポイントを叩いてから本APIを呼ぶ。
「メソッドはやりたいこと（作成=POST・部分更新=PATCH・置換=PUT）から選ぶ」「JSONボディにはContent-Type: application/jsonが要る」「Basicはbase64（暗号化ではない・HTTPS必須）」「APIキーはdocs指定の場所（ヘッダ/クエリ）と名前に厳密に従う」「BearerトークンはAuthorization: Bearer <token>で有効期限あり」が頻出です。設問は「このdocsの要求に対し、どこを直せばリクエストが通るか」で読み解きましょう。
あなたはあるSaaSのAPI docsを見ながら「ユーザ一覧を取得する」スクリプトを書き、次のcurlを実行しましたが401 Unauthorizedが返ります：curl -X GET 'https://api.example.com/v1/users' -H 'Authorization: Basic YWxpY2U6c2VjcmV0'。ここで「トークンを再発行しよう」と飛びつくのは早計で、まずdocsが要求している認証方式を読み直すのが正しい順序です。docsには「Authentication: Bearer token. Obtain a token from POST /v1/auth/token, then send Authorization: Bearer <access_token>」と書かれていました。つまりこのAPIはBasicを受け付けず、あなたは方式そのものを取り違えています。base64のYWxpY2U6c2VjcmV0はalice:secretをエンコードしただけで、暗号でも有効なトークンでもありません。正しい手順は、(1)POST /v1/auth/tokenに資格情報を送ってアクセストークンを得る、(2)そのトークンで-H 'Authorization: Bearer <access_token>'として本エンドポイントを呼ぶ、です。もし方式は合っていて（＝Bearerを送っていて）なお401なら、次に疑うのはトークンの有効期限切れで、リフレッシュして再送します。一方、認証は通ったのに403 Forbiddenなら話は別で、これは「誰かは分かったが権限が足りない」——トークンのスコープ/ロールの問題です。ここで学ぶべきは、401という一つの応答からでも、docsの要求（方式）→自分が送った値（方式・期限）→スコープという順に切り分ければ、闇雲な再試行なしに原因へ最短で到達できる、ということです。認証は「とりあえず何か付ければ通る」ものではなく、docsが指定した方式・場所・名前に一字一句合わせる作業なのです。
| 認証方式 | 送り方 | 特徴 | 失敗時の典型 |
|---|---|---|---|
| Basic認証 | `Authorization: Basic <base64(user:pass)>` | 単純・base64は暗号化ではない・HTTPS必須 | base64を安全と誤解／HTTPで平文露出 |
| APIキー | ヘッダ（例`X-Api-Key`）またはクエリ`?api_key=` | docs指定の場所・名前に厳密に従う | 場所（ヘッダ/クエリ）や名前の取り違え→401 |
| Bearerトークン | `Authorization: Bearer <token>` | 先に認証で取得（OAuth）・有効期限あり | 期限切れ→401／スコープ不足→403 |
ひっかけ： 「401が返ったらまずトークンを再発行すればよい」は誤りです——401はまずdocsが要求する認証方式と自分が送っている方式が一致しているか（例：Bearer必須なのにBasicを送っていないか）を確認するのが先で、方式が合っていて期限切れの場合に初めてリフレッシュします。また「Basic認証のbase64は暗号化なので安全」も誤り＝base64は単なるエンコードで容易に復号でき、保護は下層のHTTPS（TLS）が担います。
2.1.3この節のまとめ
- リクエストはメソッド（やりたいこと）＋エンドポイント＋ヘッダ＋（必要なら）クエリ/JSONボディで組み立て、JSONボディには
Content-Type: application/jsonを付ける - 認証はBasic（base64・HTTPS必須）／APIキー（docs指定の場所・名前）／Bearerトークン（
Authorization: Bearer・期限あり）。docsの指定に一字一句合わせる 401は「方式の不一致→期限切れ→（403なら）スコープ不足」の順で切り分け、闇雲な再発行に飛びつかない
進捗の記録にはログインが必要です。
理解度チェック
（軽い確認用）Q1. API docsに「Authentication: send the API key in the request header X-Api-Key」と明記されている。あなたは `curl 'https://api.example.com/v1/devices?api_key=ABC123'` を実行したが `401 Unauthorized` が返る。最も適切な修正はどれか。
Q2. docsは認証を「Bearer token（`POST /auth/token` で取得し `Authorization: Bearer <token>` で送る）」と定めている。あなたは正しいエンドポイントとメソッドで呼んでいるが、ボディをJSONで送っているのにサーバが本文を解釈できず `400 Bad Request` になる。まず確認すべき最も適切な点はどれか。
Q3. あるCisco系APIのdocsに「まず `POST /dna/system/api/v1/auth/token` に資格情報を送ってトークンを取得し、以降の全リクエストにそのトークンを付与する」とある。この認証モデルの理解として最も適切なものはどれか。