📮

【郵便の世界に置き換えて考える！】APIの基礎とHTTP通信の超入門講座💡

2025/06/20に公開

この記事は “APIって一体なに！？” というモヤモヤを最速で解消するための記事です。

読み終わる頃には、きっとあなたも人に説明したくてウズウズしちゃうはず…！

 0. はじめになぜAPIを学ぶのか。それはずばり、
スマホアプリでも、Webサービスでも、裏側では必ずAPIが動いているからです。
具体的には、
アプリで最新のニュースや天気を確認できる
現在地から近くのレストランを検索できる
ネットショッピングでクレジットカード決済ページに飛んで支払いができる
このように今の便利な日常生活にとって、APIは欠かせない存在になっているのです。

 1. APIとは
 1-1. 基本概念API ＝Application Programming Interface
一言でいうと

「ソフトウェア同士が安全・確実にやり取りするための窓口」　のことです。
APIがやっていることは

「利用側から来たリクエストを提供側に伝え、提供側とやり取りした結果を利用側にレスポンスする」

これだけです！

 1-2. APIの種類このAPI（＝窓口）には、以下のような種類があります。


種類
どんな窓口？
例


ライブラリ API
同じアプリ内で関数を呼ぶ
Excel関数

OS API
「コンピューターそのもの」を操作する
Windows API

Web API（≒HTTP API）
ネット越しにサーバ機能を呼ぶ
Google Maps API

今回取り扱うWeb APIの一番の特徴は 「インターネットを経由して利用できる」 というところです。

他のAPIは、利用側と提供側で開発環境が一致している必要がある一方で、Web APIは遠く離れていても、異なる環境でも、遠くの機能やデータを呼び出せます。

 1-3. 導入メリットAPIを導入すると以下のようなメリットがあります。
既製品の高度機能を即利用できる

→ 地図表示や決済などを自作せず、API にリクエストするだけで組み込める。
数行の呼び出しで開発コストと期間を圧縮できる

→ 実装が簡潔になる分、チームはコア機能に集中し納期と費用を削減できる。
品質と安全性をプロに任せられる

→ 提供元がバグ修正やスケール対応を継続しており、そのまま安心して利用できる。
このように、開発者にとってAPIは開発コスト削減や業務効率化につなげられる、なくてはならない存在なんです。

 2. 郵便ネットワークで覚えるAPIそれでは、APIがどのような仕組みになっているのかご説明します。

ここからは、インターネット上の世界を大きな郵便ネットワークだとイメージして読み進めてみてください。
この世界でのAPIは

「世界中どこへ出しても確実で読みやすい手紙のやり取りを実現する仕組み」

です。
それを実現するために登場するのが「HTTP」「REST」「JSON」です。


郵便の世界
Web の世界
具体的にどんな役割？


配達ルート+封筒
HTTP
どこを通り、どんな封筒で運ぶか

配達ルール
REST
住所のつけ方 × 配達員の動き方

手紙の本文
JSON
実際のデータ

「HTTP ルートの上を、REST ルールに従って走らせ、JSON の手紙を届ける」

ーこれ全体をまとめて提供する窓口がWeb APIです。

それでは大まかなイメージがつかめたところで、一つ一つ詳しく見ていきましょう。

 3. HTTPとは
 3-1. HTTPは「配達ルート＋封筒」HTTP = HyperText Transfer Protocol
HTTPは、インターネット上で差出人と受取人をつなぐ 「道と手順」 です。
パソコンやスマホ（差出人）がサーバー（受取人）へ手紙を投函する

→ これが HTTPリクエスト

サーバーが内容を読み取り、返事を送り返す

→ これが HTTPレスポンス
Web では「ページをください → はいどうぞ」という往復が絶えず行われています。
このとき
封筒の書き方（宛先・差出人・切手）
どのポストに入れるか
返事はどんな形式で返すか
── こうしたルール一式を決めているのが HTTP です。

 3-2. HTTPリクエストHTTPリクエストは3つのパートで構成されます。


パート
中身の例
郵便の世界


① リクエストライン
POST /articles HTTP/1.1
封筒１行目：
「速達で “/articles” 宛に荷物を送ります！」

② ヘッダー
Host: api.example.com<br>Authorization: Bearer <token><br>Content-Type: application/json
宛名ラベル・差出人の身分証・中身の種類シール

③ ボディ（任意）
{ "title": "Hello", "body": "API!" }
封筒の中に入れる手紙の本文

POST /articles HTTP/1.1　//リクエストライン
Host: api.example.com
Authorization: Bearer <token>
Content-Type: application/json　//2-5行目：ヘッダー

{ "title": "Hello", "body": "API!" }　//ボディ
リクエストは必ず、
<メソッド> <パス> <HTTPバージョン>
という一行から始まります。

メソッドは HTTP リクエストの先頭に立つ“動詞” であり、リクエスト全文の意味を決定づけるキーです。
代表的なHTTPメソッドは以下の4つです。


メソッド
説明


GET
リソースの取得

POST
リソースの新規登録

PUT
既存リソースの更新／リソースの新規登録

DELETE
リソースの削除


 3-3. HTTPレスポンスHTTPレスポンスは、クライアントからのHTTPリクエストに対する回答メッセージです。

構成はHTTPリクエストとほとんど同じで、「リクエストライン」だった部分が「ステータスライン」になります。


パート
中身の例
郵便の世界


① ステータスライン
HTTP/1.1 200 OK
郵便局が押すスタンプ：
「新しい荷物の登録が完了しました！」

② ヘッダー
Content-Type: application/json
封筒に貼られたラベル類：
「中身は書類（JSON）です」

③ ボディ（任意）
{ "id": 42, "title": "Hello", "body": "API!" }
手紙の本文

HTTP/1.1 201 Created
Content-Type: application/json

{ "id": 42, "title": "Hello", "body": "API!" }
レスポンスは必ず、
<HTTPバージョン> <ステータスコード> <短い理由句>
というステータスラインから始まります。

ステータスコードは3桁の数字で、HTTPレスポンス全体の“要約見出し” です。クライアントはまずこれを読んで次の行動を決定します。
ステータスコードが表す処理結果は、以下の5分類です。


ステータスコード
概要
例


100 番台
情報
101 Switching Protocols

200 番台
成功
200 OK

300 番台
リダイレクト
301 Moved Permanently

400 番台
クライアント側のエラー
404 Not Found

500 番台
サーバ側のエラー
500 Internal Server Error


 3-4. HTTPとHTTPSの違いHTTPSとは、セキュリティを強化したHTTPです。

HTTP の通信内容を TLSという暗号化通信技術を使って暗号化しています。
HTTPSのメリットはこちらです。

暗号化：盗み見されても内容を読めない

改ざん防止：途中で手紙を書き換えられない

サーバー証明：本当に郵便局本人か確認
この3点が担保されることで、パスワード入力やクレジット決済など機密性の高いやり取りも安心して行えており、今日ではhttpsが事実上の標準になっています。

 4. RESTとは
 4-1. RESTは「配達ルール」REST ＝Representational State Transfer

　RESTとは、「住所のつけ方（URI） と 配達員の動き方（HTTPメソッド） を定めたガイドライン」です。
まず "郵便網" にあたる HTTP があり、誰でも同じ道路を使います。
そのうえで

宛先を URI に書く

動作を GET / POST … のメソッドで示す

という２つのルールを守れば、
どの配達員（ブラウザやアプリ）でも迷わず目的の家（サーバ）へ行き、荷物を届けられる──
これが 「HTTP をいちばんシンプルかつわかりやすく使おう」 という REST の設計思想です。

 4-2. RESTの6制約その設計思想を実現するために設けられたのが、「RESTの6制約」。

　RESTful に作る＝下記 6 つの約束を守ること。 コード・オン・デマンドだけは “任意”、他は必須とされています。

 1．クライアント/サーバ分離（役割分担）Webの世界
画面（UI）とデータ管理を分離
手紙の世界
あなた（クライアント）は書いた手紙を郵便局（サーバ）へ渡すだけ。

→ あなたは郵便局が配達経路やバイクをどう手配するかは知らなくていいし、郵便局はあなたが便箋で手書きしたのか、スマホから印刷したのかなんて気にしなくていい。
メリット
両者を独立で改修できる → 開発速度・運用効率が向上！

 2．ステートレス（前回のことは忘れる）Webの世界
サーバ側はセッション状態を保存しない。
手紙の世界
あなた（差出人）は毎回、封筒に「差出人・宛先・用件」を全て記載する。
郵便局（配達員）は、その１通だけを見て配達を完了したらすべての記録を忘れる
メリット
各リクエストを独立に処理できる → 監視・障害復旧・スケールがすべて容易に！

 3．キャッシュ制御（同じ手紙はとっておく）Webの世界
「有効期限」を書いておけば途中のキャッシュが保管する。
郵便の世界

　- 町内会案内のように「しばらく変わらないもの」には、封筒に「1週間有効」と書くと、途中の支店がコピーをストック。

　→ 次に同じ依頼が来たら支店がその在庫を配るので、本局まで行かずに済んで高速。
メリット

　- クライアント/サーバー間の通信が排除 → ネットワークの混雑やサーバ負荷を大幅に削減！

 4．統一インタフェース（封筒の書き方と配達手順はそろえる）Web全体を一つの共通ネットワークとして扱えるようにするために、4つの制約が定められています。

　a. 宛先＝URI　b. 動作＝HTTP メソッド

　c. 封筒自体が自己記述的　d. 封筒の中に次の案内（HATEOAS）
ここからはこれらの制約を1つずつ見ていきます。
a. リソースの識別（住所ラベル＝URI）

　Webの世界

-　リソース（データ）はURIで一意に表す

例：https://api.example.com/books/42
郵便の世界

「〒100-0001 東京都〇〇区△△町 1-2-3 田中太郎様」
住所を書くだけで、その家の本棚の“42 番目の本”を指し示せる。
b. 表現を用いたリソース操作（指示書だけ送る）

　Webの世界

　- リソースそのものを送り返すのではなく、JSON や XML といった“表現”を介して操作する。
郵便の世界

　倉庫に保管されている荷物そのものを再配送するのではなく、「この荷札を新しい宛先に貼り替えてください」という指示書だけを封筒に入れて郵便局へ送るイメージ。

　→ 配達員は封筒を読んで荷札を更新するだけなので、荷物本体は倉庫に置いたままで済む。
c. 自己記述メッセージ（封筒に説明書）

　Webの世界

　- HTTP メソッド・ヘッダー・ステータスコードなど、メッセージの中に必要情報をすべて記載する。
郵便の世界

　- 封筒に「速達」「書留」「返送先」のスタンプ

　- 本文に「同封の写真は返却不要」など指示

　→ 配達員や検閲官は封筒を見るだけで取り扱いがわかる。
d. HATEOAS（次の案内も同封）

　Webの世界

　- レスポンスに次の操作リンクを含める

　（例）"next": "/books?page=3", "update": "/books/42"
郵便の世界
図書館からの返事に

　「関連書籍リストはこちらの目録へ → 棚番号 5-A」

　と説明文を同封してくれる。

　→ 受取人はマニュアルを読まずとも、次に何をすればよいかがわかる。
統一インターフェースのメリット
システムをまたいで “読みやすさ” と “互換性” を確保。
【郵便システムで覚える】統一インターフェースの4要素

　1.住所ラベルを貼る（URI）

　2.封筒の中身で指示を出す（Representation）

　3.封筒に取り扱い説明を書く（Self-descriptive）

　4.次の案内チラシも同封（HATEOAS）

 5．階層化システム（中継所を自由に挟める）Webの世界

　- ロードバランサ、CDN、認証ゲートなどを途中に自由追加。
郵便の世界
手紙が支店 → 拠点 → 本局… と何段経由されても、差出人は気にしなくていい。
メリット
セキュリティゲートやキャッシュなど、途中で機能を追加してもクライアントを変えずに済む。

 6. コードオンデマンド（必要なら小道具も同封）※任意Webの世界
必要に応じてサーバが「ちょっとしたプログラム」をクライアントへ送り、実行させてもよい（例：JavaScript）。
郵便の世界
郵便局が「この暗号ハガキを読むには同封の “解読メガネ” を装着してね」と、小道具（プログラム）を一緒に届けるイメージ。
メリット

　- クライアント側の機能を配布／更新しやすい。
【郵便システムで覚える】RESTの6制約

1.郵便局と差出人を分業

2.郵便局は前の手紙を覚えない

3.変わらないお知らせは支店でコピー

4.住所・封筒・動作は全国統一フォーマット

5.幾つ支店を経由しても OK

6.必要なら“解読メガネ”同封（任意）
これを守れば、Web上のデータを誰とでも・どこからでも・同じ作法で安全にやり取りできます。

 5. JSONとは
 5-1. JSONは「手紙の本文」JSON =JavaScript Object Notation
JSONは、コンピュータ同士がデータをやり取りする時のフォーマットの一つです。

　先ほどのHTTPのメッセージ構造の中の "ボディ" 部分で梱包される手紙の本文にあたります。
フォーマットはほかにも、XMLやJSONPなどたくさんありますが、以下のような理由でJSONが使われるのが主流です。
軽くて読みやすい
どのプログラミング言語でもすぐ読める
ブラウザのJavaScriptと親和性が高い
このようにJSONを使うメリットが大きく、みんな使う → 便利な道具が増える → さらにみんな使う…と雪だるま式に広まりました。

 5-2. JSONの基本構造JSONは、2種類の入れ物と4種類の荷物でできています。

　イメージは、入れ物が "箱"、基本データがその箱に貼る"ラベル（荷札）" です。

 2つの入れ物 ～オブジェクトと配列～a. オブジェクト（object）

　- 波かっこ { } で挟む箱。

　- 中（ラベル）は「キー（key）: 値（value）」のペアをカンマ , で区切って並べる。

　- キーは必ずダブルクォーテーション " " で挟む。
{
      "name": "Taro",
      "age": 20
    }
→ 「name」「age」というラベルが貼られた1つの箱。
b. 配列（array）
角かっこ [ ] で挟む箱。
値を順番にカンマ , で区切る。
    [ "red", "green", "blue" ]
→ 赤・緑・青のブロックが横一列に並んだ箱。

 4つの基本データ ～箱に入る荷物～JSONでは、次のデータ型が使用可能です。オブジェクトや配列の中に入る "ブロック" になります。
文字列（String）：ダブルクォーテーションで囲まれた文字列
"example": "Hello!"
数値（Number）：整数や浮動小数点数
"age": 25
真偽値（Boolean）：trueまたはfalse
"isActive": true
null：値が存在しないことを示す
"middleName": null
この4種類＋さきほどの2つの入れ物（オブジェクト/配列）だけで、複雑なデータも表現できます。

 入れ子構造オブジェクトの中に配列、その配列の中にオブジェクト…と、「箱 in 箱」を好きなだけ重ねて書くことができます。
{
  "orderId": 1234,
  "items": [
    { "name": "book",  "qty": 2 },
    { "name": "pen",   "qty": 5 }
  ],
  "shipping": {
    "address": {
      "city":  "Tokyo",
      "zip":   "100-0001"
    },
    "fragile": true
  }
}
＜イメージ＞

・大箱（オブジェクト）：出荷伝票 orderId 付き

　├─ 小箱（配列）items

　│　  ├─ 小箱①：book×2

　│　  └─ 小箱②：pen×5

　└─ 小箱 shipping

　　　  └─ さらに小箱 address（市区・郵便番号）

 6. 「HTTP」「REST」「JSON」をどう組み合わせる？HTTP、REST、JSONについて概要がわかったところで、お互いにどのように連携しているのか確認します。
☆あなたが「新しい荷物を送りたい」と思ったら…
REST のルールに従い、POST メソッドで、

JSON に荷物を詰めて、

HTTP の道路を通り、

サーバという倉庫に届ける。
返送されるときも同じ。だから

「HTTP＝インフラ」「REST＝規則」「JSON＝中身」とすると、
APIは「倉庫（サーバ）の受付カウンター／荷受け窓口」という位置づけになります。
つまり API は「倉庫の中身には直接触れさせず、決められた窓口で荷物をやり取りさせる仕組み」なんです。🚚💨

 7. まとめ💡API = HTTP（配達ルート） × REST（配達ルール） × JSON（手紙）
HTTP：手紙が郵便網を巡って宛先に届くように、HTTPはデータ通信のための“道”。
REST：宛名の書き方・速達スタンプ・1 通完結など、RESTはAPIの利用ルールを提供。
JSON：軽量で取り扱いやすいパッケージとして、JSONはデータを効率的に運ぶ形式。
実務では、「JSONを詰めたREST準拠のHTTPリクエスト」をAPI窓口へ投函し、レスポンスを解読するだけ。

　これがスマホアプリやWebサービスの裏側で毎秒行われることで、世界統一フォームの郵便サービスを実現、つまり「Web全体をひとつの共通ネットワーク」として扱うことを可能にしているのです。

【郵便の世界に置き換えて考える！】APIの基礎とHTTP通信の超入門講座💡

0. はじめに

1. APIとは

1-1. 基本概念

1-2. APIの種類

1-3. 導入メリット

2. 郵便ネットワークで覚えるAPI

3. HTTPとは

3-1. HTTPは「配達ルート＋封筒」

3-2. HTTPリクエスト

3-3. HTTPレスポンス

3-4. HTTPとHTTPSの違い

4. RESTとは

4-1. RESTは「配達ルール」

4-2. RESTの6制約

1．クライアント/サーバ分離（役割分担）

2．ステートレス（前回のことは忘れる）

3．キャッシュ制御（同じ手紙はとっておく）

4．統一インタフェース（封筒の書き方と配達手順はそろえる）

5．階層化システム（中継所を自由に挟める）

6. コードオンデマンド（必要なら小道具も同封）※任意

5. JSONとは

5-1. JSONは「手紙の本文」

5-2. JSONの基本構造

2つの入れ物～オブジェクトと配列～

4つの基本データ～箱に入る荷物～

入れ子構造

6. 「HTTP」「REST」「JSON」をどう組み合わせる？

7. まとめ

Discussion

種類	どんな窓口？	例
ライブラリ API	同じアプリ内で関数を呼ぶ	Excel関数
OS API	「コンピューターそのもの」を操作する	Windows API
Web API（≒HTTP API）	ネット越しにサーバ機能を呼ぶ	Google Maps API

郵便の世界	Web の世界	具体的にどんな役割？
配達ルート+封筒	HTTP	どこを通り、どんな封筒で運ぶか
配達ルール	REST	住所のつけ方 × 配達員の動き方
手紙の本文	JSON	実際のデータ

パート	中身の例	郵便の世界
① リクエストライン	`POST /articles HTTP/1.1`	封筒１行目：「速達で “/articles” 宛に荷物を送ります！」
② ヘッダー	`Host: api.example.com<br>Authorization: Bearer <token><br>Content-Type: application/json`	宛名ラベル・差出人の身分証・中身の種類シール
③ ボディ（任意）	{ "title": "Hello", "body": "API!" }	封筒の中に入れる手紙の本文

メソッド	説明
GET	リソースの取得
POST	リソースの新規登録
PUT	既存リソースの更新／リソースの新規登録
DELETE	リソースの削除

パート	中身の例	郵便の世界
① ステータスライン	`HTTP/1.1 200 OK`	郵便局が押すスタンプ：「新しい荷物の登録が完了しました！」
② ヘッダー	Content-Type: application/json	封筒に貼られたラベル類：「中身は書類（JSON）です」
③ ボディ（任意）	`{ "id": 42, "title": "Hello", "body": "API!" }`	手紙の本文

ステータスコード	概要	例
100 番台	情報	101 Switching Protocols
200 番台	成功	200 OK
300 番台	リダイレクト	301 Moved Permanently
400 番台	クライアント側のエラー	404 Not Found
500 番台	サーバ側のエラー	500 Internal Server Error

0. はじめに

1. APIとは

1-1. 基本概念

1-2. APIの種類

1-3. 導入メリット

2. 郵便ネットワークで覚えるAPI

3. HTTPとは

3-1. HTTPは「配達ルート＋封筒」

3-2. HTTPリクエスト

3-3. HTTPレスポンス

3-4. HTTPとHTTPSの違い

4. RESTとは

4-1. RESTは「配達ルール」

4-2. RESTの6制約

1．クライアント/サーバ分離（役割分担）

2．ステートレス（前回のことは忘れる）

3．キャッシュ制御（同じ手紙はとっておく）

4．統一インタフェース（封筒の書き方と配達手順はそろえる）

5．階層化システム（中継所を自由に挟める）

6. コードオンデマンド（必要なら小道具も同封）※任意

5. JSONとは

5-1. JSONは「手紙の本文」

5-2. JSONの基本構造

2つの入れ物 ～オブジェクトと配列～

4つの基本データ ～箱に入る荷物～

入れ子構造

6. 「HTTP」「REST」「JSON」をどう組み合わせる？

7. まとめ

Discussion

2つの入れ物～オブジェクトと配列～

4つの基本データ～箱に入る荷物～