1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@code_thought

API入門

1
Posted at

API 初心者向け「いまさら聞けない API の全体像」整理メモ

REST / GraphQL / gRPC / FastAPI / 同期 / 非同期 …
「単語は聞いたことあるけど、頭の中で整理できてない」人向けのざっくり整理用記事です。

この記事では、API の世界を以下の 4+α の観点で整理します。

  • API のスタイル（設計スタイル）
  • 呼び出しパターン（同期 / 非同期 / リアルタイムなど）
  • フレームワーク & 言語
  • プロトコル & データ形式
  • （おまけ）セキュリティ / 認証
  • （その他）バージョニング、ドキュメント など

実務で API に触るときに、
「これはどの軸の話をしているのか？」
を意識できるようになるのがゴールです。

1. まずは「API の世界地図」をざっくり

API 周りの用語は、だいたい以下の複数の軸に分類できます。

  1. スタイル（設計スタイル）

    • REST-ish HTTP API（いわゆる REST）
    • RPC / gRPC
    • GraphQL
    • SOAP、Webhook、イベント駆動 など

  2. 呼び出しパターン

    • 同期（リクエスト → レスポンス）
    • 非同期（ジョブ + ポーリング、Webhook、キュー）
    • リアルタイム（WebSocket / SSE）

  3. フレームワーク & 言語

    • Python: FastAPI / Django REST Framework / Flask …
    • Node.js: Express / NestJS …
    • Java: Spring Boot …
    • Go: Gin …
    • .NET: ASP.NET Core … など

  4. プロトコル & データ

    • HTTP/HTTPS, HTTP/2, HTTP/3
    • WebSocket
    • gRPC（HTTP/2 + Protobuf）
    • JSON / XML / Protobuf / form-data …

  5. セキュリティ / 認証（ざっくり）

    • API キー
    • OAuth2 / OpenID Connect
    • JWT
    • mTLS など

  6. その他の観点

    • バージョニング
    • ドキュメント（OpenAPI/Swagger, GraphQL Schema 等）
    • 「内部 API / 公開 API / パートナー API」などの位置づけ

たとえばこんな言い方をしているとき：

「うちは Spring Boot で REST API を作ってて、
外部公開は同期 HTTP、内部のマイクロサービス同士は gRPC。」

この一文だけで、上の軸のうち
スタイル / フレームワーク / 呼び出しパターン / プロトコル
が一気に指定されている、というイメージです。

2. API のスタイル（設計スタイル）

2-1. REST-ish HTTP API（いわゆる REST）

現代の Web API の「デフォルト」的な存在です。
教科書的な REST というより、実務ではだいたい REST っぽい HTTP + JSON API（REST-ish）と思っておくと精神的に楽です。

基本発想

  • すべては「リソース」として扱う
    • /users … ユーザ一覧というリソース
    • /users/123 … ID=123 のユーザ
    • /orders/456/items … 注文 456 の明細
  • HTTP メソッドで「何をするか」を表す
    • GET /users/123 … ユーザ取得（READ）
    • POST /users … ユーザ作成（CREATE）
    • PATCH /users/123 … 部分更新（UPDATE）
    • DELETE /users/123 … 削除（DELETE）
  • レスポンスはほぼ JSON 一択（歴史的には XML も）

例

GET /users/123 HTTP/1.1
Accept: application/json

{
  "id": 123,
  "name": "Taro",
  "email": "taro@example.com"
}

最も一般的な話だと

「REST っぽい URL + HTTP メソッド + JSON」をセットで
「REST API」と呼んでいるケースがほとんどです。

2-2. RPC スタイル API & gRPC

RPC（Remote Procedure Call） は

「リモートで関数を呼びたい」イメージのスタイルです。

RPC っぽい HTTP API の例

URL が「リソース名」ではなく「動詞」寄りになります。

POST /sendEmail
POST /calculatePrice
POST /users/123/activate

REST と比べると：

  • REST

PATCH /users/123 with {"status": "ACTIVE"}

  • RPC：

POST /activateUser with {"id": 123}

何が違うか？

  • REST：

    • 「モノ（リソース）」を中心に考える

  • RPC：

    • 「やりたいこと（アクション）」を中心に考える

gRPC

gRPC は、Google 発の 高速な RPC フレームワーク です。

  • HTTP/2 上で動く

  • データは Protobuf（バイナリ形式 & スキーマ有り）

  • クライアント / サーバのコードを自動生成しやすい

  • ストリーミング（ストリーム RPC）も得意

使いどころ：

  • マイクロサービス同士の内部通信

  • 高パフォーマンスが必要な場面

2-3. GraphQL

GraphQL は「API のクエリ言語 + 実行ランタイム」というポジションです。

REST との大きな違いは：

  • REST：サーバ側が「このエンドポイントではこの JSON を返す」と決める

  • GraphQL：クライアント側が「こういう形のデータが欲しい」と宣言する

例：ユーザと最近 5 件の記事を取得

query {
  user(id: 123) {
    name
    avatarUrl
    posts(limit: 5) {
      title
      createdAt
    }
  }
}

レスポンスはそのまま欲しい構造の JSON が返ります。

メリット

  • 画面 1 つのために REST だと 3〜5 回 API を叩くところが
    GraphQL だと 1 回で済む、というケースが多い

  • 過不足ないデータ取得（Over-fetch / Under-fetch の解消）

デメリット寄りポイント

  • サーバ実装が複雑になりがち（resolver の設計など）

  • キャッシュ戦略やモニタリングが REST と違う

REST をやめて全部 GraphQL に、という話ではなく、
「データを柔軟に組み合わせて取得したい場面」で選択肢に入る
くらいの理解がちょうど良いです。

2-4. SOAP（軽く触るだけ）

SOAP は XML ベースのプロトコルで、
銀行・保険・官公庁系の古めのシステムでまだまだ現役です。

  • WSDL という契約（インタフェース定義）ファイルを持つ

  • セキュリティ、トランザクション、信頼性等の仕様が厚い

新規開発だとあまり選ばれませんが、
「レガシー連携で出会う可能性が高い」ので名前だけでも知っておくと安心です。

2-5. Webhook / イベント駆動

ここは「スタイル」というよりはシステム間連携の考え方ですが、
API 実務ではよく出てくるので一応ここで。

  • Webhook：

    • あなたが「コールバック用 URL」を相手に登録

    • 相手側でイベント（例：決済完了）が起きたら、その URL に HTTP リクエストが飛んでくる

  • イベント駆動アーキテクチャ：

    • サービス A が「イベント」をメッセージキュー / ストリームに発行

    • サービス B/C が購読して処理する

3 呼び出しパターン（同期 / 非同期 / リアルタイム）

同じ REST API でも、「どう使うか」という呼び出し方で分類すると理解しやすくなります。

3-1. 同期（Synchronous）

もっとも基本的なパターンです。

  • クライアントがリクエストを送る

  • レスポンスが返ってくるまで待つ

  • レスポンスを受けて次の処理をする

ユーザ操作に対してすぐ結果が欲しい場面（ログイン、登録、検索など）はほぼこれです。

3-2. 非同期（Asynchronous）

「すぐ結果が出ない処理」「時間がかかる処理」に対してたくさんのパターンがあります。

3-2-1. ジョブ + ポーリング

1.クライアントが重い処理を依頼する：

  • POST /export → {"job_id": "abc-123"} が返る

2.一定間隔で GET /jobs/abc-123 を叩いて状態を確認する：

{
  "id": "abc-123",
  "status": "running",
  "progress": 42
}

よくある用途：

  • レポート出力
  • 大量データのバッチ処理
  • AI 推論のバッチ

3-2-2. Webhook / コールバック

1.クライアントが相手サービスに「コールバック URL」を登録

2.相手サービス側で処理が完了したタイミングで、その URL に POST してくる

用途：

  • 決済サービス（決済結果の通知）

  • 外部ログイン / 認証後の通知

  • 外部バッチサービス

3-2-3. メッセージキュー / イベント駆動

  • フロントエンド → バックエンド → メッセージキュー（Kafka 等）

  • バックグラウンドワーカーがキューから取り出して処理

用途：

  • メール送信
  • プッシュ通知
  • ログ集約
  • 非同期の連携処理

3-3. リアルタイム通信（WebSocket / SSE）

WebSocket

  • サーバとクライアントが双方向の長い接続を張る

  • チャット、オンラインゲーム、リアルタイムモニタリングなど

SSE（Server-Sent Events）

  • サーバ→クライアントの片方向ストリーム

  • ログストリーム、進捗表示、LLM のストリーミングレスポンスなどで使われることも

4. フレームワーク & 言語

ここは「API を実装するとき何を使うか？」という話です。
フレームワーク = API を作るための道具 であり、
REST / GraphQL / gRPC などのスタイルとは別軸です。

4-1. Python 系

  • FastAPI

    • 型ヒント + 自動ドキュメント（OpenAPI）
    • async/await 対応
    • 「サクッと REST-ish API を作る」のにとても人気

  • Django + Django REST Framework (DRF)

    • 管理画面や認証など、Web アプリ + API をまとめてやりたいとき
    • 伝統的な業務系システムでよく使われる

  • Flask

    • 軽量で自由度が高い
    • 必要な機能を自分で組み合わせる感じ

4-2. Node.js 系

  • Express

    • 一番よく聞く名前
    • シンプルで学習コスト低い

  • NestJS

    • TypeScript 前提
    • DI やモジュール構造が整っていて、大規模開発向け
    • 「Spring Boot の Node 版」みたいなイメージ

4-3. Java 系

  • Spring Boot

    • エンタープライズ系ではデファクトスタンダード
    • REST API も gRPC も書ける

  • Micronaut / Quarkus など

    • より軽量 / クラウドネイティブ指向

4-4. .NET / C# 系

  • ASP.NET Core
    • マイクロソフト系スタックで API を作るときの第一候補

4-5. Go 系

  • Gin
    • 軽量で高速、人気が高い
  • その他：Echo, Fiber など

4-6. ざっくりまとめ

言語 よく聞くフレームワーク例 一言でいうと
Python FastAPI, Django REST, Flask 書きやすさ・ツールの多さ
Node.js Express, NestJS JS/TS フルスタックでやりたいとき
Java Spring Boot エンタープライズの王道
.NET ASP.NET Core Microsoft スタックと相性良し
Go Gin, Echo シンプル & 高パフォーマンス

5. プロトコル & データ形式

5-1. HTTP / HTTPS / HTTP/2 / HTTP/3

API と言えばまずは HTTP/HTTPS です。

  • HTTP/1.1

    • いちばん基本のバージョン
    • 現在も多くの API がこの前提で動いている

  • HTTP/2

    • 1 つの TCP コネクションで複数リクエストを同時に流せる（マルチプレックス）
    • ヘッダ圧縮によりオーバーヘッド削減
    • gRPC などは HTTP/2 前提で設計されている

  • HTTP/3

    • UDP ベースの QUIC を利用
    • ネットワーク品質が悪い環境でも、接続が切れにくい
    • 大規模サービスやブラウザでは徐々に普及中

多くの場合、アプリケーション開発者は「HTTP（あるいは HTTPS）」として意識しておけば十分ですが、
裏では HTTP/2 / 3 が使われている、というケースもあります。

5-2. WebSocket

  • HTTP のハンドシェイクをきっかけに、サーバとクライアントの間に「双方向の長い接続」を張るプロトコル
  • 一度接続すると、サーバからクライアントへも自由にデータをプッシュできる

使いどころの例：

  • チャットアプリ
  • オンラインゲーム
  • 株価やセンサー値などのリアルタイムモニタリング
  • バックエンドからのプッシュ通知

5-3. gRPC（HTTP/2 + Protobuf）

gRPC は、Google が OSS として公開している RPC フレームワークです。

特徴：

  • HTTP/2 の上で動作する
  • データは Protobuf（Protocol Buffers）というバイナリ形式で送受信
  • .proto ファイルという IDL（インタフェース定義）から、各言語向けのクライアント / サーバコードを自動生成できる
  • 一方向ストリーム / 双方向ストリームなど、ストリーミング通信もサポート

向いている場面：

  • マイクロサービス同士の内部通信
  • 高トラフィック・高パフォーマンスが要求される API
  • サーバ / クライアント双方で型安全に開発したいとき

外部向けの公開 API は分かりやすさ重視で REST/JSON、
内部向けは効率重視で gRPC、という組み合わせもよくあります。

5-4. データ形式

API で扱うデータ形式はさまざまですが、実務でよく使うのはまずこのあたりです。

  • JSON（JavaScript Object Notation）

    • 現代の Web API ではほぼ標準
    • 人間にも読みやすく、ブラウザ / モバイル / サーバのどこでも扱いやすい

  • XML

    • 以前は主流だったが、今は新規開発では少なめ
    • SOAP や一部の古い仕様・業界標準ではまだよく出てくる

  • Protobuf（Protocol Buffers）

    • gRPC で標準採用されているバイナリ形式
    • スキーマ（.proto）に基づき、型安全にシリアライズ / デシリアライズされる
    • 軽量・高速だが、人間が直接読むのには向かない

その他：

  • フォームデータ（application/x-www-form-urlencoded）
    • HTML のフォーム送信などでおなじみの形式
  • マルチパート（multipart/form-data）
    • ファイルアップロードを伴う API でよく使われる形式

まずは「人間向けには JSON、機械向けの高効率が必要なら Protobuf」というくらいの感覚で OK です。

6. セキュリティ / 認証（ざっくり）

ここは掘るとかなり深い領域ですが、名前と用途だけでも押さえておくと API 設計全体のイメージがつきやすくなります。

6-1. API キー

  • ランダムな文字列を発行し、クライアントに配布
  • クライアントはリクエストヘッダやクエリパラメータにそのキーを付与
  • サーバ側は「このキーは誰のものか」「有効かどうか」をチェックする

よくある形の一例：

  • ヘッダに載せるパターン
    • X-API-Key: xxxxxxxxxxxxxxxxx
  • Authorization ヘッダに載せるパターン
    • Authorization: Bearer xxxxxxxxxx

用途：

  • 外部向けのシンプルな公開 API
  • サーバ to サーバ間の認証（内部連携）

6-2. OAuth2 / OpenID Connect

OAuth2 は「ユーザの資源へのアクセス権限を第三者に委譲する」ための枠組みです。

  • 「Google アカウントでログイン」
  • 「GitHub アカウントでログイン」
  • 「このアプリに Google Drive への読み取り権限を与える」

といったものは、ほとんど OAuth2 / OpenID Connect の応用です。

ポイント：

  • ユーザのパスワードを第三者アプリに渡さずに、権限だけを委譲できる
  • アクセストークン / リフレッシュトークンなどの概念が出てくる
  • API 自体というより「認証・認可のフロー」を決めるための仕様

API を利用する側としては、

  • 「どのエンドポイントに飛ぶべきか」
  • 「どのタイミングでどのトークンを使うか」

といった点だけ押さえておけば、最初は十分です。

6-3. JWT（JSON Web Token）

JWT は、JSON データを署名付きトークンにしたものです。

  • ヘッダ・ペイロード・署名の 3 部分から構成される
  • ペイロード部に、ユーザ ID、ロール、トークン有効期限などを入れることが多い
  • サーバ側は署名をチェックすることで「このトークンが改ざんされていないか」を検証できる

特徴：

  • 「サーバ側にセッションを持たない」設計との相性が良い
  • 複数のサービス間で同じトークンを使い回せる（シングルサインオン的な構成）

注意点：

  • 一度発行したトークンの無効化やローテーションなど、運用設計がやや難しい
  • ペイロード自体は Base64 エンコードされているだけなので、暗号化ではない（見ようと思えば中身は見える）

6-4. mTLS（双方向 TLS）

通常の HTTPS は「サーバ側だけが証明書を持ち、クライアントがそれを検証する」形です。

  • ブラウザがサーバ証明書を検証し、「本当に example.com か？」をチェックしてくれる

一方、mTLS（mutual TLS）では、クライアント側も証明書を持ちます。

  • サーバはクライアント証明書を検証し、「このリクエストは本当に正当なクライアントから来ているか？」を確認できる
  • 金融機関同士や、社内 VPN 内の重要システム間通信など、セキュリティの要求が高い場面で使われる

7. その他（バージョニング / ドキュメント / API の種類）

7-1. API バージョニング

API は一度公開すると「互換性」が重要になります。

  • 古いクライアントも、新しいクライアントも、同時に存在する
  • 変更の内容によっては、古いクライアントが動かなくなってしまう

そのため、破壊的変更を行う場合は バージョン を切るのが一般的です。

よくあるパターン：

  • URL にバージョンを含める
    • /api/v1/users
    • /api/v2/users
  • HTTP ヘッダでバージョンを示す
    • Accept: application/vnd.example.v2+json

また、フィールドの追加・削除などについては、

  • 追加は「なるべく既存クライアントに影響がない形」で行う
  • 削除は「非推奨（deprecated）」期間を設けた上で、十分な告知の後に行う

といった運用ルールを決めておくと、後々楽になります。

7-2. ドキュメント & 契約（Contract）

良い API ほどドキュメントが整備されています。

代表的な手段：

  • OpenAPI / Swagger
    • REST-ish HTTP API を記述するための標準フォーマット
    • FastAPI, Spring Boot, NestJS など多くのフレームワークが、自動生成機能を持っている
  • GraphQL のスキーマ（SDL）
    • GraphQL の型定義自体がそのまま API 契約になる
  • gRPC の .proto ファイル
    • RPC メソッドとメッセージ型の定義
    • そのままコード生成にも使える

ここまで来ると、API のドキュメントは単なる説明文ではなく、
「機械も読める API 契約（Contract）」になっていると言えます。

7-3. 内部 API / 公開 API / パートナー API

「誰のための API か？」という観点も大事です。

  • 内部 API

    • 自社サービス同士の連携用
    • パフォーマンス・開発効率・内部アーキテクチャとの整合性が重視される
    • gRPC や、内部限定の REST API など

  • 公開 API（Public API）

    • 外部の一般開発者向け
    • 分かりやすさ・安定性・長期的な互換性・レート制限・課金などが重要
    • ドキュメントや SDK をセットで提供することも多い

  • パートナー API

    • 特定の企業やパートナーとの連携用
    • 契約ベースで仕様を合意し、個別の制約や要件を取り込むことも多い

8. まとめ：API を理解するときの「軸」を意識する

ここまで見てきた内容を、「どの軸の話か？」という観点で整理しなおします。

  1. スタイル（設計スタイル）
    • REST-ish / RPC / gRPC / GraphQL / SOAP / Webhook / イベント駆動
  2. 呼び出しパターン
    • 同期 / 非同期（ジョブ + ポーリング、Webhook、キュー）/ リアルタイム（WebSocket / SSE）
  3. フレームワーク & 言語
    • FastAPI / Django REST / Express / NestJS / Spring Boot / ASP.NET Core / Gin など
  4. プロトコル & データ
    • HTTP/HTTPS, HTTP/2, HTTP/3, WebSocket, gRPC
    • JSON / XML / Protobuf / form-data / multipart など
  5. セキュリティ / 認証
    • API キー / OAuth2 / OpenID Connect / JWT / mTLS … など
  6. その他
    • バージョニング
    • ドキュメント（OpenAPI, GraphQL Schema, .proto）
    • 内部 API / 公開 API / パートナー API といった位置づけ

新しい用語が出てきたときに、

  • これは「スタイル」の話か？
  • それとも「フレームワーク」の話か？
  • 「呼び出しパターン」や「プロトコル」の話ではないか？

と一度立ち止まってみると、頭の中の API 情報がだいぶ整理されてきます。

おまけ：これから実際に手を動かすなら

もし Python が使えるなら、入門用のミニプロジェクトとしては次のようなものがオススメです。

  • FastAPI で TODO 管理の REST-ish API を作る
    • /todos で一覧取得・登録
    • /todos/{id} で取得・更新・削除
  • その中の 1 機能（例：TODO 一覧の CSV エクスポート）だけ、非同期ジョブ + ポーリング方式にする
    • POST /export でジョブ作成（job_id が返る）
    • GET /jobs/{job_id} で進捗確認

このくらいの規模でも、

  • スタイル（REST-ish）
  • 呼び出しパターン（同期 / 非同期）
  • フレームワーク（FastAPI）
  • プロトコル & データ（HTTP + JSON）
  • 認証（簡易なトークンチェックなど）

といった要素を一通り体験できます。

この記事の内容を「頭の整理」に使いつつ、
実際に手を動かしてみると理解が一気に深まるはずです。

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?