こんにちは。
昨夜は息子の小学校の父親達の集まり、通称「オヤジ会」に出席し、久し振りに少し飲み過ぎて若干二日酔い気味ではありましたが、本日もいつも通り CCNA の学習は実施しました。
今回は Automation and Programmability 基礎（第3回） として、API の本人確認、返事の意味、やり取りの流れ を中心に整理しました。
昨日までは REST API や JSON などの言葉を「なんとなく聞いたことがある」という段階でしたが、今回はそれらが実際にどうつながって動くのかを見ていく内容で、少しずつ理解の輪郭がはっきりしてきた感覚があります。
今更ではありますが、API という言葉の意味も改めて気になって調べてみました。
API とは Application Programming Interface の略で、ソフトウェアやプログラム同士をつなぐ「窓口」や「接点」のことです。別のシステムが持つ機能やデータを、自分のプログラムから呼び出して使うための仕組みだと考えると、かなりイメージしやすいと思います。今回の学習でも、API は「お願いを出す窓口」として整理すると理解しやすく感じました。
Request / Response とは何か
API 通信では、まずこちらから相手へ「これをしてほしい」と送る依頼があり、これを Request（リクエスト） と呼びます。
そして、その依頼に対して相手から返ってくる「できました」「できません」「これが結果です」という返事が Response（レスポンス） です。
つまり API は、ただ一方的に命令を投げるものではなく、依頼を送り、その結果を返してもらうやり取り で成り立っています。
今回のキャプチャでも、クライアントが Request を送り、サーバーや API、コントローラが Response を返す流れが非常に分かりやすく図解されていて、まずはこの往復のイメージを持つことが大切だと感じました。
Request の中には何が入るのか
Request の中には、単に「お願いしたい内容」だけが入っているわけではありません。
HTTP request は大きく start-line、headers、body で構成されます。start-line には HTTP メソッド、対象、HTTP バージョンが入り、headers には追加情報、body には必要な本文データが入ります。
やさしく言い換えると、Request には「どこに送るか」「何をしたいか」「どんな形式で送るか」「必要なら本文を送る」という情報が入ります。
今回の学習スライドでも、URL、HTTP verb、header、JSON body と順番に整理されていて、API 通信の流れを一本で見るのにとても役立ちました。 キャプチャ2
Authentication とは何か
Authentication は、やさしく言えば 本人確認 のことです。
今回の学習では、認証なしの None (No Auth) に加えて、Basic Authentication、API Key、OAuth、Bearer Token といった考え方を整理しました。
公開 API のように認証が不要なものもありますが、多くの API では安全のために何らかの本人確認が必要になります。今回の内容を通して、「API も人と同じで、まず本人確認が必要」という感覚で捉えると分かりやすいです。
Basic認証・APIキー・トークンをどう区別するか
Basic Authentication は、「ユーザ名＋パスワード」で本人確認する方式です。
一方で API Key は、「この鍵を持っているなら使ってよい」という考え方に近い方式です。
そして Token / Bearer Token は、一度認証してから、その後の通信で使う通行証のようなものを受け取って使うイメージです。
つまり、Basic は「ID とパスワード」、API Key は「専用の鍵」、Bearer Token は「あとから使う通行証」と整理するとかなり分かりやすくなります。
HTTP headers をやさしく見る
HTTP headers は、リクエストやレスポンスに添える補足情報です。
今回の学習では、特に Content-Type、Accept、Authorization の3つを押さえました。
Content-Type は、「こちらが送るデータ形式は何か」を示すヘッダです。
POST や PUT のようなリクエストでは、クライアントが Content-Type を使ってサーバーへ送信内容の種類を伝える必要があります。
Accept は、「どんな形式で返してほしいか」を示すヘッダです。
たとえば Accept: application/json と書けば、「JSON 形式で返してほしい」という希望を相手へ伝えることができます。これは、クライアントが理解できるデータ形式を知らせるためのものです。
Authorization は、認証情報を送るためのヘッダです。
Authorization ヘッダは保護されたリソースへアクセスするための資格情報を提供するために使われるものです。Basic 認証や Bearer Token も、このヘッダに入れて使うのが基本です。
HTTP status codes とは何か
HTTP status codes は、API から返ってくる結果の番号つきメッセージです。
HTTP ステータスコードはリクエスト結果を示すコード群で、成功、リダイレクト、クライアントエラー、サーバーエラーなどに分類されています。
今回の学習では、特に次のコードを押さえました。
200 OK は成功、201 Created は新規作成成功、204 No Content は成功したが返す本文はない、301 Permanently Moved は URL の恒久移動です。
さらに 400 Bad Request はリクエストの書き方が不正、401 Unauthorized は認証がない・無効、403 Forbidden は権限不足、404 Not Found は対象が見つからない、500 Internal Server Error はサーバ側の一般エラー、503 Service Unavailable はサービス利用不可という意味になります。
status code をやさしく分類する
status code は細かい番号を全部暗記する前に、まず大きな分類で見ると分かりやすいです。
MDN では、2xx は成功、4xx はクライアント側の問題、5xx はサーバー側の問題 と整理されています。
今回のキャプチャでも、
2xx ＝ うまくいった、
4xx ＝ こちら側の問題、
5xx ＝ 相手側の問題、
という形でまとめられていて、とても理解しやすい構成でした。
番号の細かい意味がまだ曖昧でも、「まず大分類でつかむ」だけでかなり見通しがよくなると感じました。
401 と 403 の違い
今回の中でも特に混同しやすいと感じたのが、401 と 403 の違いです。
401 Unauthorized は実質的には「未認証」に近く、認証情報がない、または正しくない状態を意味します。一方 403 Forbidden は、認証は通っていても、そのリソースや操作に対する権限がないため拒否される状態です。
やさしく言うと、401 は入口で止められる状態、403 は中には入れたけれど、その操作は許可されていない状態 です。
この違いが見えてくると、エラーが出たときに「認証の問題なのか、権限の問題なのか」を切り分けやすくなると思いました。
API request / response の流れを一本で見る
API 通信の流れを一本で見ると、まず URL を指定 し、次に HTTP verb で何をしたいかを決め、そのうえで header に形式や認証情報を入れ、必要であれば JSON body を送る 形になります。
そしてサーバーやコントローラがそれを処理し、最後に status code と必要なデータを response として返す という流れです。
つまり API は、ただの抽象的な概念ではなく、宛先・操作・条件・本文・返事 という流れで具体的にやり取りされる仕組みなのだと、今回かなり実感できました。
今回の学習で感じたこと
昨日までの段階では、API 関連の言葉はそれぞれがバラバラに浮かんでいる感じで、正直かなり抽象的に見えていました。
ただ今回は、Request / Response、Authentication、headers、status code、JSON body といった要素をひとつの流れとして見られたことで、ようやく「API 通信がどう動いているのか」の輪郭がつかめてきた気がします。
文系出身の自分にとっては、こういう分野は最初からカチッと理解するというより、ぼんやりしたものが少しずつ形になっていく感覚 のほうがしっくりきます。
今回の学習は、まさにその感覚に近く、「まだ完璧ではないけれど、昨日より確実に見えてきた」と感じられる内容でした。
まとめ
今回は Automation and Programmability 基礎（第3回） として、API の本人確認・返事の意味・やり取りの流れ を整理しました。
API 通信では、まず Request を送り、Response を受け取り、その中で Authentication による本人確認、headers による条件指定、status code による結果確認が行われます。
さらに、必要に応じて JSON body を使ってデータを渡し、相手からも JSON 形式で結果を受け取ることがあります。
こうして見ると、API は単なる難しい言葉ではなく、依頼を出して、条件を添えて、番号つきの返事をもらう仕組み と考えるとかなり理解しやすいと感じました。
まだ抽象的に感じる部分はありますが、少なくとも今回は「API がどんな流れで動くのか」を前より具体的にイメージできるようになりました。
今後は、ここで学んだ status code や認証方式を見ながら、少しずつ実際の API のやり取りにも慣れていきたいと思います。
コメント