Zenn
🗣️

Web APIの基礎（前編）：概念からリソース設計編やでー

2025/03/11に公開
API
基本
restful
OpenAI API
tech

こんにちは！本記事は2部構成になっています！
自身の学習記録かつWebAPIの基礎知識を初学者向けに記事化しました！

APIとは？

API（Application Programming Interface）とは、ソフトウェア同士が互いにコミュニケーションを取るための仕組みです。Web APIは、インターネットを通じてデータやサービスにアクセスするための窓口のようなものです。

例えば：

  • 天気アプリが天気データを取得するために天気予報APIを使用
  • SNSアプリがユーザーの投稿をTwitterやFacebookに共有するためにそれぞれのAPIを使用
  • ECサイトが支払い処理のためにPayPalやStripeのAPIを使用

主要なWeb APIの種類と違い

現在主流のWeb API方式には主に3つのタイプがあります：

1. REST API

RESTful API（Representational State Transfer）は最も広く使われているWeb API方式で、HTTPプロトコルの特性を活かしたシンプルな設計原則に基づいています。

特徴：

  • HTTPメソッド（GET, POST, PUT, DELETE）を使用してリソースを操作
  • URLでリソースを表現（例：/users/123はID 123のユーザーリソース）
  • ステートレス（各リクエストは独立して処理される）
  • クライアント-サーバーアーキテクチャ
  • 主にJSONやXML形式でデータをやり取り
GET /api/users/123 HTTP/1.1
Host: example.com

2. GraphQL

Facebookが開発した比較的新しいAPI技術で、必要なデータだけを柔軟に取得できることが特徴です。

特徴：

  • 単一エンドポイントで全てのリクエストを処理
  • クライアントが必要なデータ構造を指定可能
  • オーバーフェッチやアンダーフェッチの問題を解決
  • 強力な型システム
query {
  user(id: "123") {
    name
    email
    posts {
      title
    }
  }
}

3. gRPC

Googleが開発した高性能なRPC（Remote Procedure Call）フレームワークです。

特徴：

  • Protocol Buffersを使用した効率的なデータシリアライズ
  • 高速で低レイテンシーな通信
  • 多言語対応
  • 双方向ストリーミングのサポート
  • マイクロサービスアーキテクチャに適している
syntax = "proto3";

service UserService {
  rpc GetUser(UserRequest) returns (User) {}
}

message UserRequest {
  string user_id = 1;
}

message User {
  string user_id = 1;
  string name = 2;
  string email = 3;
}

比較表

特性 REST GraphQL gRPC
通信プロトコル HTTP HTTP HTTP/2
データ形式 JSON/XML JSON Protocol Buffers
エンドポイント 複数 単一 サービス定義
学習曲線 低〜中 中 中〜高
キャッシング 簡単 複雑 複雑
ブラウザサポート ネイティブ ネイティブ 要ライブラリ
適したユースケース CRUD操作中心のAPI 複雑なデータ取得、モバイル マイクロサービス、高性能要件

HTTPリクエスト・レスポンスの基本

Web APIの多くはHTTPプロトコルを基盤としています。HTTPリクエストとレスポンスの基本を理解しましょう。

HTTPリクエスト

クライアントがサーバーに送信する情報で、以下の要素で構成されます：

  1. リクエストライン：メソッド、URI、HTTPバージョン
  2. ヘッダー：メタ情報（Content-Type, Authorization等）
  3. ボディ：送信するデータ（POSTやPUTリクエスト時など）

例：

POST /api/users HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "name": "山田太郎",
  "email": "yamada@example.com"
}

主要なHTTPメソッド

メソッド 用途 特徴
GET データの取得 ボディなし、キャッシュ可能、冪等性あり
POST リソースの作成 ボディあり、キャッシュ不可、冪等性なし
PUT リソースの置換/更新 ボディあり、キャッシュ不可、冪等性あり
PATCH リソースの部分更新 ボディあり、キャッシュ不可、冪等性なし
DELETE リソースの削除 ボディなし/あり、キャッシュ不可、冪等性あり

冪等性（べきとうせい）：同じ操作を何度行っても結果が変わらない性質

HTTPレスポンス

サーバーがクライアントへ返す情報で、以下の要素で構成されます：

  1. ステータスライン：HTTPバージョン、ステータスコード、説明
  2. ヘッダー：メタ情報（Content-Type, Cache-Control等）
  3. ボディ：返送するデータ

例：

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/users/456

{
  "id": 456,
  "name": "山田太郎",
  "email": "yamada@example.com",
  "created_at": "2023-04-01T12:00:00Z"
}

主要なHTTPステータスコード

HTTPステータスコードは、リクエストの処理結果を3桁の数字で表します。

1xx（情報）

  • 100 Continue: 継続
  • 101 Switching Protocols: プロトコル切り替え

2xx（成功）

  • 200 OK: リクエスト成功
  • 201 Created: リソース作成成功
  • 204 No Content: 成功したが返すコンテンツなし

3xx（リダイレクト）

  • 301 Moved Permanently: 恒久的リダイレクト
  • 302 Found: 一時的リダイレクト
  • 304 Not Modified: キャッシュされたコンテンツが最新

4xx（クライアントエラー）

  • 400 Bad Request: 不正なリクエスト
  • 401 Unauthorized: 認証が必要
  • 403 Forbidden: アクセス権限なし
  • 404 Not Found: リソースが見つからない
  • 422 Unprocessable Entity: リクエスト形式は正しいが処理できない

5xx（サーバーエラー）

  • 500 Internal Server Error: サーバー内部エラー
  • 502 Bad Gateway: ゲートウェイエラー
  • 503 Service Unavailable: サービス利用不可

リソース指向設計

RESTful APIの設計では、「リソース」を中心に考えます。リソースとは、ユーザー、商品、記事など、システム内の実体や概念を表します。

リソースの特定と命名

  1. リソースの名詞化：動詞ではなく名詞を使用

    • 良い例: /users, /products
    • 悪い例: /getUsers, /createProduct

  2. 複数形の使用：コレクションリソースには複数形を使用

    • 例: /users, /articles

  3. 具体的なリソースには識別子を使用

    • 例: /users/123, /articles/best-practices

  4. リレーションシップの表現：親子関係は階層構造で表現

    • 例: /users/123/posts (ユーザー123の投稿一覧)

  5. クエリパラメータの活用：フィルタリング、ソート、ページネーション

    • 例: /products?category=electronics&sort=price&page=2

エンドポイント設計の実例

ブログシステムのAPIを例に考えてみましょう：

操作 HTTPメソッド エンドポイント 説明
記事一覧取得 GET /api/articles 全記事を取得
記事詳細取得 GET /api/articles/{id} 特定の記事を取得
記事作成 POST /api/articles 新しい記事を作成
記事更新 PUT /api/articles/{id} 記事を完全に更新
記事部分更新 PATCH /api/articles/{id} 記事を部分的に更新
記事削除 DELETE /api/articles/{id} 記事を削除
記事コメント一覧 GET /api/articles/{id}/comments 記事のコメントを取得
記事コメント追加 POST /api/articles/{id}/comments 記事にコメントを追加

リクエスト・レスポンスのデータ設計

データの設計にも一貫性が重要です：

リクエストの例（記事作成）:

POST /api/articles HTTP/1.1
Content-Type: application/json

{
  "title": "Web APIの基礎",
  "content": "APIとは...",
  "tags": ["programming", "api", "web"]
}

レスポンスの例:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/articles/456

{
  "id": 456,
  "title": "Web APIの基礎",
  "content": "APIとは...",
  "tags": ["programming", "api", "web"],
  "author": {
    "id": 123,
    "name": "山田太郎"
  },
  "created_at": "2023-04-01T12:00:00Z",
  "updated_at": "2023-04-01T12:00:00Z",
  "_links": {
    "self": { "href": "/api/articles/456" },
    "comments": { "href": "/api/articles/456/comments" }
  }
}

RESTful設計のベストプラクティス

  1. 統一インターフェース：HTTPメソッドを適切に使用し、一貫したレスポンス形式を提供

  2. リソース間のリンク：HATEOAS（Hypermedia as the Engine of Application State）の考え方を採用し、関連リソースへのリンクを提供

  3. バージョニング：APIの互換性を保つためのバージョン管理

    • URLベース: /api/v1/users
    • ヘッダーベース: Accept: application/vnd.example.v1+json

  4. 適切なステータスコード：処理結果を正しく表現するステータスコードを使用

  5. 一貫したエラーレスポンス：エラー情報を統一フォーマットで提供

    {
  "status": 400,
  "message": "Invalid request parameters",
  "errors": [
    {"field": "email", "message": "Invalid email format"}
  ]
}

OpenAPI (Swagger) を活用したAPI設計

OpenAPI仕様（旧Swagger）は、RESTful APIを記述するための標準フォーマットです。APIの設計、文書化、テスト、クライアントコード生成などに役立ちます。

OpenAPIの利点

  • API設計の統一性と一貫性の確保
  • 自動ドキュメント生成
  • クライアントコードの自動生成
  • モックサーバーの自動生成
  • API設計先行開発（API First）の促進

OpenAPI仕様の例

基本的なユーザーAPIをOpenAPI 3.0で記述した例：

openapi: 3.0.0
info:
  title: ユーザーAPI
  description: ユーザー情報を管理するためのAPI
  version: 1.0.0
paths:
  /users:
    get:
      summary: ユーザー一覧の取得
      responses:
        '200':
          description: ユーザー一覧
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: 新規ユーザーの作成
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: ユーザー作成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{userId}:
    get:
      summary: 特定ユーザーの取得
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ユーザー情報
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: ユーザーが見つからない
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
        created_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - email
    UserInput:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
      required:
        - name
        - email

OpenAPIのツール

  • Swagger Editor：OpenAPI仕様の作成・編集
  • Swagger UI：APIドキュメントの可視化
  • Swagger Codegen：クライアントコード・サーバースタブの自動生成

ここまで読んでいただきありがとうございました。
以上で前編は終わりです。後編では認証・認可、キャッシュ戦略、エラー処理、CORSなどについてです！よろしくお願いいたします！

Discussion