Web APIの基礎

TL;DR

• Web APIはHTTPを使って機能やデータを外部に公開するインターフェース
• 代表的なスタイルはREST・GraphQL・gRPC。現在のWeb開発ではRESTが主流
• NestJS / Express などのフレームワークを使ってサーバー側で実装する

Web APIとは

Web APIは「Web上でやり取りするためのインターフェース」である。

たとえば、次のようなケースで使われる。

• フロントエンド（React / Next.js）がバックエンドからデータを取得する
• モバイルアプリがサーバーにデータを送信する
• サービスAがサービスBの機能を呼び出す（外部連携）

仕組みはシンプルで、クライアントがHTTPリクエストを送り、サーバーがHTTPレスポンスを返す。

クライアント（ブラウザ / モバイルアプリ / サーバー）
  ↓ HTTPリクエスト
Web APIサーバー
  ↓ HTTPレスポンス（JSON など）
クライアント

レスポンスの形式は現在ほぼJSONが標準となっている。

代表的なWeb APIのスタイル

REST API

最も広く使われているスタイル。HTTPメソッド（GET / POST / PUT / DELETE）とURL（エンドポイント）を使ってリソースを操作する。

GET  /users       # ユーザー一覧取得
POST /users       # ユーザー作成
GET  /users/1     # ID=1 のユーザー取得
PUT  /users/1     # ID=1 のユーザー更新
DELETE /users/1   # ID=1 のユーザー削除

詳しくは REST APIの基礎 を参照。

GraphQL

FacebookがOSSとして公開したクエリ言語ベースのAPIスタイル。エンドポイントは1つ（通常 /graphql）で、クライアントが取得したいフィールドを指定する。

query {
  user(id: 1) {
    name
    email
  }
}

RESTとの主な違い：

モバイルアプリや複雑なデータ構造を持つサービスで採用されることが多い。

gRPC

GoogleがOSSとして公開した、Protocol Buffersを使う高速なAPIスタイル。JSON ではなくバイナリ形式でやり取りするため、パフォーマンスが高い。

service UserService {
  rpc GetUser (GetUserRequest) returns (User);
}

マイクロサービス間の内部通信や、パフォーマンスが求められる場面で使われる。ブラウザから直接呼び出すには制限があるため、公開APIよりも内部通信向け。

WebSocket

HTTP をアップグレードして、サーバー・クライアント間の双方向通信を実現する仕組み。一度接続を確立すると、サーバー側から能動的にデータを送信できる。

チャットやリアルタイム通知など、「サーバーからプッシュしたい」場面で使われる。

詳しくは WebSocketの基礎 を参照。

どのスタイルを選ぶか

実務では REST がデファクトで、特別な理由がなければ REST から始めるのが自然な選択である。

Web APIの実装イメージ

Node.jsでは NestJS や Express を使って実装する。たとえば NestJS では Controller がエンドポイントを担当し、Service がビジネスロジックを持つ。

// ユーザー取得エンドポイントの例（NestJS）
@Controller('users')
export class UsersController {
  constructor(private usersService: UsersService) {}

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.usersService.findOne(+id);
  }
}

NestJS でのCRUD API実装は NestJSでCRUD APIを作る で詳しく扱っている。

関連記事

• REST APIの基礎 — RESTの設計原則と考え方
• HTTPステータスコードの使い分け — レスポンスで返すべきコードの判断基準
• OpenAPIの基礎 — API仕様書の書き方と共有方法
• NestJSでCRUD APIを作る（Prisma + SQLite） — NestJSでのREST API実装の実践
• WebSocketの基礎 — リアルタイム通信の仕組み