WebAPI と REST

[RESTの一次情報：Roy Fielding's doctoral dissertation](https://ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)

https://apidog.com/


Webエンジニアを目指すとWeb API と REST という言葉がよく出てきます。
本記事では、これについてキャッチアップします。

まず、用語を整理します。
- Web
    - World Wide Webの略
    - なんとなく分かると思うので割愛[WWWについてはこちら](https://qiita.com/hirokishimizu39/items/1dc36a1b41ffc1fba3aa)
    - 一番わかりやすくいうと、よくいうネット（インターネット）
- API
    - `Application` `Programming` `Interface`の略
    - つまり、`アプリ`と`プログラム`の`繋ぎ目`
    - ある`アプリ例えばInstagram`から、`外部のプログラム例えばgoogle map`、を`繋ぐ`　これをAPIという。

- Web API
    - Webの文脈における、API
    - つまり、インターネットを使用する際に、アプリとプログラムを繋いでくれるもの

- REST
    - `REpresentational` `State` `Transfer`の略
    - `具象化された` `状態`の`転送`
    - 以下、JSONで記述した`具象化された状態`の例
```json
{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "age": 25,
  "createdAt": "2023-06-01T10:00:00Z"
}
```
| 概念       | JSON内で対応する部分                              |
| -------- | ----------------------------------------- |
| 具象化された | JSON形式（構造化され、人が理解でき、機械も読める）               |
| 状態     | `name`, `email`, `age`, `createdAt` などの属性 |
| 転送     | ネットワークを通じて、クライアントへこの「状態」が届く               |

- REST API
    - 「RESTの原則にしたがって作られたAPI」のこと
    - クライアント（例：ブラウザやスマホアプリ）とサーバーが、リソース（例：ユーザー、投稿、商品など）をやりとりするための窓口
    - 特徴は、「状態（データ）を、具象化された形（JSONなど）で、転送してやりとりする」という点
    - 例えば、`GET /users/123` と送ると、そのユーザーの状態（データ）を表現したJSONが返ってくる

<br>

📦 REST APIの例：
リクエスト

```
GET /users/123
```

レスポンス

```json
{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com"
}
```

ここでは「users/123というリソースの状態」を、「JSON形式で具象化」して、「ネットワークで転送」している


REST APIのイメージまとめ 🎨
- レストランの注文のようなもの。
- 客（クライアント）は「ハンバーガーをください（GET /burgers/1）」と注文し、
- 店（サーバー）は「この状態のバーガーです」と写真（JSON）を返す。
- 客は直接キッチンに入らず、写真（具象化された状態）でやり取りする。






> 👦 REST＝「具象化された状態の転送（Representation of State Transfer）」とわざわざいうくらいだから、RESTではない設計思想を持つAPIもあるってことかな？

結論：**YES**
例えば、以下がある。
- GraphQL
- RPC
- gRPC


| スタイル        | 状態を具象化？ | 転送の焦点       | イメージ（レストラン）                                       | 簡単なコード例                                                                                       |
| ----------- | ------- | ----------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **REST**    | ✅ yes   | 状態（リソース）    | メニューから「カレー」を注文し、**決まった具材すべて**が届く（ルー・肉・じゃがいも・にんじん） | `GET /menu/curry`<br>`→ { name: "Curry", ingredients: ["roux", "meat", "potato", "carrot"] }` |
| **GraphQL** | ⚠️ yes(部分的) | 状態（クエリベース）  | 「カレーの**ルーとじゃがいもだけ**ください」と注文。**必要なものだけ**を取得できる     | `graphql<br>{ curry { roux, potato } }<br>→ { curry: { roux: true, potato: true } } `         |
| **RPC**     | ❌ no  | 処理（操作）      | ウェイターに「**水を持ってきて**」と**操作そのもの**を依頼                 | `POST /bringWater`<br>`→ { status: "ok" }`                                                    |
| **gRPC**    | ❌ no  | 処理（高速・内部通信） | 厨房スタッフ同士が「**皿洗って**」などを**高速・効率的にやり取り**             | `service Kitchen { rpc WashDishes(WashRequest) returns (WashResponse); }`                     |







🥇 REST：具象化された状態の転送
- サーバーが「あるリソースの状態のスナップショット（representation）」を返す
- クライアントはその状態を取得・変更する
```
📦 例：
GET /users/123 → { "name": "Alice", "age": 25 }

🧠 イメージ：
展示室の写真を受け取って、編集してまた送り返す
```


🥈 RPC（Remote Procedure Call）：関数呼び出し型のAPI
- サーバーの「操作（関数）」を直接呼び出す感覚
- 状態の具象化は意識せず、「この処理をして」と伝える
```
📦 例：
POST /createUser with body { "name": "Alice", "age": 25 }

🧠 イメージ：
電話をかけて「この作業やって」と口頭で依頼する
🔁 状態の転送ではなく、「動作」のリクエストが中心
```


🥉 GraphQL：クライアント主導で状態の選択的取得
- クライアントが必要なデータ構造を宣言して取得
- 状態は転送されるが、具象化の粒度はクライアントが決める

```graphql
📦 例：
query {
  user(id: 123) {
    name
    age
  }
}
🧠 イメージ：
レストランでオーダーシートに「欲しいものだけ」を書いて出す

✔️ 「状態を転送」はするが、「具象化の仕方」がRESTとは異なる
```


🏅 gRPC：型安全＆高速なRPC通信（主にマイクロサービス間）
- プロトコルバッファ（protobuf）を使ってバイナリ形式で通信
- RESTよりも**「内部システム間の手続き呼び出し」に特化**
- 状態の概念というより、関数を安全に・効率的に呼ぶ
```
📦 例：
UserService.CreateUser() という関数を直接呼び出す

🧠 イメージ：
高性能な社内メッセンジャーで一瞬で指示を送る
```