「APIの仕組みってなんだか難しそう…」。
そんなあなたのために、Web APIとREST APIを「ピザの電話注文」に例えてわかりやすく解説します！
「注文の流れ＝データのやり取り」をイメージすれば、APIの概念がスッと頭に入るはず！
APIがわかれば、自分で作るアプリに取り込むことも可能です。
Web APIとREST APIについて、楽しく学んでいきましょう！
Web APIの基本を図解でわかりやすく説明しているYoutubeサイトです。前半で知識を学び、後半では実際にAPIを作る過程を紹介しています。
このブログ記事では、APIの活用事例やメリット・デメリットについて詳しく解説しています。特にWeb APIに焦点を当てており、初心者の方にも理解しやすい内容です。
Web APIとは？
Web API（Web Application Programming Interface）とは、異なるシステムやアプリケーションがインターネットを介してデータをやり取りするための「窓口」です。
この機能を使うことで、自分のコンピューターやアプリに他のアプリケーションの機能を追加したりすることができます。
Web APIをピザ屋の電話注文に置き換えると？
Web APIをピザ屋の電話注文に置き換えると、次のようになります。
ピザを食べたいのですが自分で作るのは大変なのでピザを作ってもらおうと思ってます。
- あなた：「ピザを1枚ください！」
- ピザ屋受付：「注文来たよ」（とピザ屋の職人に伝える）
- ピザ屋：「OK。了解」（とピザ屋職人がピザ屋受付に伝える）
- ピザ屋受付：「かしこまりました。30分以内にお届けします。」
このように、あなた（クライアント）とピザ屋（サーバー）は電話を使い「ピザ屋受付」を介して注文のやり取りをしています。これがWeb APIの概略です。
ただここでのやり取りは大雑把なので、他の店では通用しない可能性があります。
そこでREST APIというものが出てきます。
REST APIとは？
REST APIは、Web APIの中でも特定のルール（REST: Representational State Transfer）に従ってデータをやり取りするAPIのことです。シンプルで統一された方法で情報をやり取りできるため、多くのWebサービスで採用されています。
REST APIの特徴は以下になります。
- リソース指向：データは「リソース」として扱われ、特定のURL（エンドポイント）でアクセス可能。
- HTTPメソッドの活用：GET、POST、PUT、DELETEなどのHTTPメソッドを使用。
- ステートレス（Stateless）：各リクエストは独立しており、前回のリクエスト状態をサーバーが保持しない。
REST APIをピザ屋の注文に例えると？
REST APIでは、統一されたリソースのアドレス（エンドポイント）に対して、決められたメソッドを使って操作を行います。
ピザ屋の電話注文に置き換えると以下のようになります。
- あなた：行動：注文します 情報：会員情報は・・・ 言語は・・・ 詳細：マルゲリータ
- ピザ屋受付：返答：注文受付けました 情報：日時は・・・ 詳細：マルゲリータ、30分後・・・
このように決まった方式でやり取りするのがREST APIになります。
多くのWeb APIはこのREST APIに沿った形式になっています。
次からはこのピザ屋を例として書き方について学んでいきます。
REST APIのメソッドとステータスコード
REST APIのメソッド（ピザ屋での注文行動）
REST APIのメソッドは、クライアントがサーバーに対してどのような操作を行うかを決めるものです。
ピザ屋の電話注文に例えると、注文を確認したり、新しく注文を行ったり、注文内容を変更したり、注文をキャンセルしたりする行動に相当します。
- GET：メニュー教えてください（相手の持っている情報をもらう）
- POST：マルゲリータSサイズ1枚お願いします（相手に情報を渡す）
- PUT/PATCH：やっぱりLサイズで、アンチョビ追加で
- DELETE：注文キャンセルします
これをテーブルでまとめると以下のようになります。
| メソッド | 役割 | ピザ屋での例 |
|---|---|---|
| GET | 情報の取得 | 「どんなピザがありますか？」 |
| POST | 新しい注文の作成 | 「マルゲリータ S サイズ 1 枚お願いします。」 |
| PUT/PATCH | 既存注文の変更 | 「やっぱり L サイズでアンチョビ追加で！」 |
| DELETE | 注文のキャンセル | 「注文をキャンセルします。」 |
注文の仕方が固定されているのが特徴です。
REST APIでのステータスコード（ピザ屋からの返答行動）
サーバーはクライアントからのリクエストに対して適切なステータスコードを返します。
これは、ピザ屋が電話注文に対して「受け付けました」「その注文はありません」「システムに問題が発生しています」などと返答するのと同じです。
ピザ屋の電話注文に置き換えると以下のようになります。
以下に、ステータスコードの例を示します。
- 成功:200番台
OK。受付けました（200 OK)
注文作成しました(201 Created) - クライアント（あなた）エラー:400番台
サイズ指定方法が無効です（400 Bad Request)
会員情報が間違ってます(401 UnAuthorized)
あなたに権限はないです(403 Forbidden)
注文が見つかりません（404 Not Found) - サーバー（ピザ屋）エラー:500番台
ピザ屋のキャパオーバーです(500 Internal Server Error)
今日は定休日です(501 Service Unavailable)
テーブルでまとめると以下のようになります。
| 状況 | ステータスコード | 状態 | ピザ屋での例 |
| 成功 | 200 OK | 成功 | 「注文を受け付けました！」 |
| 201 Created | 注文作成成功 | 「注文を作成しました！」 | |
| クライアントエラー | 400 Bad Request | リクエストエラー | 「サイズの指定方法が無効です。」 |
| 401 Unauthorized | 認証エラー | 「会員情報が間違っています。」 | |
| 403 Forbidden | アクセス権なし | 「あなたに権限はありません。」 | |
| 404 Not Found | リソースなし | 「注文が見つかりません。」 | |
| サーバーエラー | 500 Internal Server Error | サーバーエラー | 「ピザ屋のキャパオーバーです。」 |
| 503 Service Unavailable | 一時的な障害 | 「今日は定休日です。」 |
返答の仕方も固定されているのが特徴です。
REST APIの要素
REST APIは、メソッドとステータスコード以外にもいろいろな要素があります。
それぞれの要素について詳しく説明します。
リクエスト側（ピザ屋での電話注文）
リクエスト側はメソッド以外にも、ヘッダーやリクエストボディというものが存在します。
これはピザ屋の電話注文に例えると「情報」、「詳細」に当たります。
図にすると以下のようになります。
- 行動（HTTPメソッド）
HTTPメソッドは、リクエストの種類を示します。
GET, POST, PUT, PUTCH, DELETE - 情報（ヘッダー）
ヘッダーは、リクエストに関する追加情報を伝えます。
店舗情報：HOST
話す言語：Content-Type
会員情報：Authorization - 詳細（リクエストボディ）
リクエストボディには、実際の注文内容や変更内容が含まれます。
注文者の名前:customer_name
ピザの種類：item
サイズ：size
配送先：delivery_adress
このようにリクエストでは注文の要素が決まっています。
レスポンス側（ピザ屋での電話返答）
レスポンスにおいてもステータスコード以外に、ヘッダー、レスポンスボディが存在します。
これもピザ屋の電話注文に例えると「情報」、「詳細」に当たります。
図にすると以下のようになります。
- 返答（ステータスコード）
ステータスコードは、リクエストの成功・失敗を示す数値です。
OK（200）
あなたの問題（400）
ピザ屋の問題(500) - 情報（ヘッダー）
ヘッダーは、レスポンスの追加情報を伝えます。
話す言語：Content-Type
日時：Date - 詳細（レスポンスボディ）
レスポンスボディには、実際の注文情報やエラーメッセージが含まれます。
注文番号:order_id
ピザの種類：item
ピザのサイズ：size
配送時間：estimated_time
このようにレスポンスでも返答の要素が決まっています。
まとめ
Web APIは、インターネットを介してデータをやり取りする「窓口」のようなもの。
REST APIは、その中でも統一されたルール（REST）で情報をやり取りするAPIです。
ピザ屋の電話注文の例を用いることで、REST API の仕組みを直感的に理解することができます。
APIを理解できると自分で作るアプリに組み込むことができます。
さらに生成AIのAPIと組み合わせることで無限大の可能性が広がります。
私の書いている書籍なども参考ください。
コメント