mybook

プロローグ — APIファーストで始める

ナツミ、新しいプロジェクトに挑む

渋谷のスタートアップ、Livly（リブリー）。 フルスタックエンジニアのナツミは、入社3年目にして初めてモバイルアプリ向けAPIの設計リードを任された。

「今回はiOSとAndroidの両方に対応しながら、将来的にはWebフロントも共通のAPIで動かしたい」

CTOの槙島さんからのオーダーは明快だった。しかしナツミには一つの疑問があった。

「Railsでふつうにサーバーサイドレンダリングしてきたけど、APIって何が違うの？」

その答えを探す旅が、今始まる。

モバイル時代のバックエンド

かつてWebアプリ開発は「フロントエンドとバックエンドが一体」だった。RailsのERBテンプレートでHTMLを生成し、ブラウザに返す——それが標準だった。

しかし2010年代から状況は大きく変わった。

Loading diagram...

スマートフォンの普及により、1つのバックエンドが複数のクライアントに対応する必要が生まれた。

INFO

APIファーストとは：UIより先にAPIの設計・実装を行うアプローチ。どのクライアントからも同じデータにアクセスできる「共通基盤」を作ることが目的。

ナツミが直面した現実

Livlyの既存システムはRailsモノリスだった。管理画面はERBテンプレート、一部のデータはAjaxで取得——という混在状態。

「これをモバイルアプリ向けに拡張するには？」

ナツミはまず現状を整理した。

# 既存のコントローラ（ERBテンプレート前提）
class PropertiesController < ApplicationController
  def index
    @properties = Property.all
    # respond_to なし → HTMLしか返せない
  end
 
  def show
    @property = Property.find(params[:id])
  end
end

これをAPIに対応させるだけなら簡単だ。

# API対応への第一歩
class PropertiesController < ApplicationController
  def index
    @properties = Property.all
 
    respond_to do |format|
      format.html  # index.html.erb
      format.json { render json: @properties }
    end
  end
end

しかし槙島CTOは首を振った。

「それはAPIファーストじゃない。API専用のコントローラを切り出して、設計から見直してほしい」

APIファーストの3つのメリット

ナツミは設計の勉強を始めた。APIファーストには明確なメリットがある。

1. クライアントに依存しない

iOSアプリ、Androidアプリ、Webフロント、外部サービス——すべてが同じAPIを使う。UIの変更がバックエンドに影響しない。

2. 並行開発が可能

APIの仕様（Contract）を先に決めれば、フロントエンドとバックエンドを同時に開発できる。

Loading diagram...

3. テストが書きやすい

HTMLレスポンスのテストはDOMに依存するが、JSONレスポンスのテストは純粋なデータ検証で済む。

Livlyのスタック選定

ナツミと槙島CTOは技術選定を行った。

レイヤー選択肢採用
API形式REST / GraphQL / gRPCREST（まず基礎から）
認証APIキー / JWT / OAuth2JWT + OAuth2
ドキュメントSwagger / RedocOpenAPI + rswag
デプロイEC2 / ECS / LambdaAWS ECS

WARNING

技術選定の落とし穴：最初からGraphQLやgRPCを使いたくなるが、チームがREST APIの基礎を理解していないと設計が破綻する。まずRESTをしっかり習得することが重要。

AWSアーキテクチャの全体像

Livlyのインフラは以下のように設計された。

Loading diagram...

API Gatewayがリクエストの入口となり、認証・レート制限・ログ収集を担当する。実際のビジネスロジックはECS上のRailsコンテナが処理し、RDS（PostgreSQL）とElastiCache（Redis）を使う。

この本で学ぶこと

ナツミとともに、ゼロからAPIを設計・実装する旅に出よう。

  1. RESTful設計 — リソース設計とHTTPメソッドの正しい使い方
  2. シリアライゼーション — 美しいJSONレスポンスの作り方
  3. 認証 — APIキーからOAuth2まで
  4. エラーハンドリング — 開発者に優しいエラー設計
  5. パフォーマンス — キャッシュで速いAPIを作る
  6. GraphQL — 必要なデータだけ取得する
  7. gRPC — 高速な内部通信
  8. テスト — 品質を担保する
  9. ドキュメント — 使われるAPIを作る
  10. Developer Experience — APIエコシステムの構築

INFO

ナツミのゴール：6ヶ月後に、iOSとAndroidのLivlyアプリが動く、安全でスケーラブルなAPIを本番リリースすること。

まとめ

  • モバイルファーストの時代、APIは「後付け」ではなく「設計の起点」
  • APIファーストにより、複数クライアントへの対応・並行開発・テストが容易になる
  • RailsはAPI開発に強力な機能を持つ（api_only モード、名前空間、シリアライザーなど）
  • AWSのAPI GatewayとECSを組み合わせてスケーラブルなインフラを構築する

次章では、RESTful APIの設計原則——リソースの命名規則からHTTPメソッドの使い方まで——を学ぶ。

次の章RESTful API の設計原則