会社情報
採用情報
お問い合わせ
Article

APIファースト開発のススメ：設計段階から始める効率的なシステム構築

高田晃太郎
APIファースト開発のススメ：設計段階から始める効率的なシステム構築

要求定義での欠陥を運用段階で修正するとコストは最大で100倍に膨らむとされる古典的な研究があります¹²。さらに、ガートナーの試算として広く引用される数字では、システム停止は1分あたり5,600ドルの損失になり得ます³。PostmanのState of the APIでも、回答者の大多数がAPI投資を維持または増やすとし、APIが事業の中核である現実が定着しています⁴。複数の公開事例やデータを踏まえると、要件の曖昧さと境界のゆらぎが再作業と障害の主要因になりやすく、設計を契約として先に固定するAPIファーストは、それらを初期段階で断ち切るための実務的な打ち手になり得ます。

ここでは、スローガンではなく実装に踏み込みます。OpenAPIで仕様（＝契約）を作り、モックを動かし、サーバとクライアントを生成し、CIで仕様逸脱を検知し、パフォーマンスとSLOまで仕様由来のガードレールで守る。CTOやリードエンジニアが今のスプリントから着手できる、実戦的なプロセスとコードを提示します。

APIファーストの要点：契約がソース・オブ・トゥルースになる

APIファーストは、エンドポイントを後追いでドキュメント化するのではなく、要求と応答、エラーや認可、レート制御、バージョニングといった振る舞いを契約として先に定義し、組織内外のステークホルダーがその契約を唯一の真実として共有する考え方です。ここでいう契約は機械可読なAPI仕様（OpenAPIやAsyncAPI）⁵⁶を指し、そこからモック、テスト、サーバスタブ、クライアントSDK、さらにリント（静的検査）と互換性チェックまでを自動化します⁷。実装は契約の下位成果物となり、仕様とコードの乖離が構造的に抑制されます。

実務で効くのは、契約が非機能要件（機能以外の品質特性）も包含できる点です。スループットやレイテンシのSLO（サービス目標値）、ページネーションや並び順、エンティティの一意性と冪等性（同じ操作の再試行で結果が変わらない性質）、エラーレスポンスの構造、キャッシュやバージョン方針。こうした合意がないまま開発に入ると、結合時に設計の解釈違いが露出し、スプリント複数回分の遅延につながりがちです。契約を先に固めると、意思決定の速度が上がり、フィードバックも早期に降り、後戻りのコスト曲線を抑えられます。

成功の鍵はドメインモデリングと境界の明確化にある

契約を正確にするには、ユースケースからドメイン語彙を抽出し、リソース、関係、状態遷移を言語化することが欠かせません。単なるフィールド一覧ではなく、識別子の安定性、時間の扱い、部分更新の粒度、整合性の厳密さを意識して構造化することが重要です。例えば「注文と顧客」「在庫とSKU」のようにリソース関係を先に定義し、ID体系やタイムスタンプの扱い（UTC/ISO 8601）、部分更新の方法（PATCH/PUTの適用範囲）まで書き分けます。非機能要件は仕様の一等市民に据えます。ページネーションのカーソル方式かオフセット方式か、ソートの安定性、レート制御の単位時間、冪等性キーの適用範囲、そして廃止予定の宣言タイミング。こうした合意をYAMLの文言として残すことが、レビューと将来の機能拡張を堅くします。

設計から実装まで：契約駆動の実装例

まずは最小でも価値あるスコープをOpenAPIで表現します。作り込みすぎる必要はありませんが、スキーマの再利用とエラー標準化、そして冪等性とキャッシュの方針は最初から入れておくと後が楽になります。（冪等性は再試行の安全性、ETagはコンテンツの識別子です）

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /orders:
    post:
      summary: Create order
      operationId: createOrder
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NewOrder' }
      responses:
        '201':
          description: Created
          headers:
            ETag: { schema: { type: string } }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '409':
          description: Conflict on duplicate idempotency key
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
    get:
      summary: List orders
      operationId: listOrders
      parameters:
        - name: cursor
          in: query
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/Order' }
                  nextCursor: { type: string, nullable: true }
components:
  schemas:
    NewOrder:
      type: object
      required: [customerId, items]
      properties:
        customerId: { type: string }
        items:
          type: array
          items:
            type: object
            required: [sku, qty]
            properties:
              sku: { type: string }
              qty: { type: integer, minimum: 1 }
    Order:
      allOf:
        - $ref: '#/components/schemas/NewOrder'
        - type: object
          required: [id, createdAt]
          properties:
            id: { type: string }
            createdAt: { type: string, format: date-time }
            status: { type: string, enum: [PENDING, CONFIRMED] }
    Error:
      type: object
      required: [code, message]
      properties:
        code: { type: string }
        message: { type: string }
        details: { type: object, additionalProperties: true }

契約ができたら、生成と検証を回します。モックは手作りせずに契約から起動します。Prismのようなツールを使うと、レスポンスをサンプルから返し、バリデーションも行えます⁸。

# OpenAPIのモックサーバを起動
npx @stoplight/prism-cli mock openapi.yaml --port 4010

サーバ側は契約でガードされた実装にします。Node.jsであれば、Expressにバリデータを挟み込み、契約違反のリクエストとレスポンスを開発段階から遮断できます⁹。エラーハンドラを用意して、契約違反時に標準化したエラー形（上記ErrorまたはRFC 7807）で返すと、クライアント実装が安定します。

import express from 'express';
import { middleware as openapiValidator } from 'express-openapi-validator';
import crypto from 'node:crypto';

const app = express();
app.use(express.json());
app.use(openapiValidator({ apiSpec: 'openapi.yaml', validateRequests: true, validateResponses: true }));

const orders = new Map<string, any>();
const idemStore = new Map<string, string>();

app.post('/orders', (req, res) => {
  const idem = req.header('Idempotency-Key');
  if (!idem) return res.status(400).json({ code: 'BAD_REQUEST', message: 'Missing Idempotency-Key' });
  const existing = idemStore.get(idem);
  if (existing) return res.status(409).json({ code: 'IDEMPOTENT_CONFLICT', message: 'Already processed' });
  const id = crypto.randomUUID();
  const order = { id, ...req.body, status: 'PENDING', createdAt: new Date().toISOString() };
  orders.set(id, order);
  idemStore.set(idem, id);
  const etag = crypto.createHash('sha1').update(JSON.stringify(order)).digest('hex');
  res.setHeader('ETag', etag);
  res.setHeader('Cache-Control', 'no-store');
  res.status(201).json(order);
});

app.get('/orders', (req, res) => {
  const limit = Math.min(Number(req.query.limit ?? 50), 200);
  const items = Array.from(orders.values()).slice(0, limit);
  res.json({ items, nextCursor: null });
});

// 契約違反などのエラーを標準化して返す
app.use((err: any, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
  const status = err.status || 500;
  res.status(status).json({ code: 'VALIDATION_ERROR', message: err.message, details: err.errors });
});

app.listen(3000, () => console.log('API listening on :3000'));

クライアントSDKは契約から生成し、型安全に呼び出します。TypeScriptの生成物を前提に、呼び出し側はビジネスロジックに専念できます⁷。

import crypto from 'node:crypto';
import { Configuration, OrdersApi } from './gen/ts';

const api = new OrdersApi(new Configuration({ basePath: 'https://api.example.com' }));
async function create() {
  const idem = crypto.randomUUID();
  const res = await api.createOrder(
    { newOrder: { customerId: 'C001', items: [{ sku: 'SKU-1', qty: 2 }] } },
    { headers: { 'Idempotency-Key': idem } }
  );
  console.log(res.data.id);
}
create();

契約の品質と互換性はCIで強制します。リントで表現の揺れを抑え、ブランチ上で破壊的変更を検出し、レビューの負荷を軽くします。

name: api-contract
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Lint OpenAPI with Spectral
        uses: stoplightio/spectral-action@v1
        with:
          file_glob: 'openapi.yaml'
      - name: Check breaking changes
        run: npx openapi-diff --fail-on-breaking main:openapi.yaml openapi.yaml

この段での静的検査にはSpectralを使い⁽¹⁰⁾、差分による破壊的変更検出にはopenapi-diffを用いると導入しやすいです¹¹。

仕様で守る品質：エラー標準化、監視、性能予算

エラーの形を統一すると、クライアントは回復戦略を実装しやすくなります。上のErrorスキーマに合わせ、エラーコードの命名規約をREADMEではなく契約の記述として残します。例えば、HTTP APIの標準的なエラー表現としてRFC 7807（Problem Details）を採用する選択肢もあります¹²。さらに、計測はエンドポイントの粒度で透過的に仕込みます。OpenTelemetry（分散トレーシングとメトリクスの標準）を用いると、トレースIDがログとメトリクスに伝播し、SLO違反の根因追跡が速くなります¹³。

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({ url: process.env.OTLP_URL }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

パフォーマンスは負荷試験で継続的に測り、しきい値に落ちたらビルドを落とします。k6のスクリプトで、p95レイテンシや失敗率をSLO（たとえば「p95<300ms」「エラー率<1%」）に合わせて監視します¹⁴。

import http from 'k6/http';
import { sleep } from 'k6';
import { Trend, Rate } from 'k6/metrics';

export const latencyP95 = new Trend('latency_p95');
export const errorRate = new Rate('error_rate');

export const options = {
  vus: 50, duration: '2m', thresholds: {
    http_req_duration: ['p(95)<300'],
    error_rate: ['rate<0.01'],
  }
};

export default function () {
  const res = http.get(`${__ENV.BASE_URL}/orders?limit=10`);
  errorRate.add(res.status >= 400);
  latencyP95.add(res.timings.duration);
  sleep(0.2);
}

キャッシュと帯域の最適化も契約に統合します。変更が少ない参照系のAPIはETagと条件付きリクエスト（If-None-Match）で差分配信を推奨し¹⁵、書き込み系は冪等性キーで再試行の安全性を担保します¹⁶。実装はヘッダーの扱いを徹底するだけで効果が出ます。

import { Request, Response } from 'express';

function withConditionalGet(req: Request, res: Response, body: any) {
  const etag = 'W/"' + Buffer.from(JSON.stringify(body)).toString('base64') + '"';
  res.setHeader('ETag', etag);
  const noneMatch = req.header('If-None-Match');
  if (noneMatch === etag) return res.status(304).end();
  res.setHeader('Cache-Control', 'private, max-age=60');
  return res.json(body);
}

互換性の破壊を避けるには、公開契約の変更規律が必要です。OpenAPIの差分チェックに加えて、クライアント契約テストを活用すると信頼性が上がります。Provider側でPactを検証し、期待されたスキーマを満たしているかCIで確認します¹⁷。

import { Verifier } from '@pact-foundation/pact';

new Verifier({
  providerBaseUrl: 'http://localhost:3000',
  pactUrls: ['https://broker.example.com/pacts/provider/OrdersAPI/latest'],
}).verifyProvider().then(() => console.log('Pact verified'));

バージョニング、廃止方針、そして組織のガバナンス

APIの進化は必然です。セマンティックバージョニングに準拠し¹⁸、非互換の導入時はURIではなくヘッダーやメディアタイプ（Content-Typeのバリエーション）でのネゴシエーションを検討します。段階的な移行にはDeprecationやSunsetヘッダーを活用し、カットオフまでの猶予を契約に刻みます¹⁹²⁰。互換性を壊す必要がある場合は、旧バージョンを維持しつつ、新バージョンでの恩恵と移行ガイドを公開してトラフィックを段階的に切り替えます。ビルド時の互換性チェック、実行時のテレメトリー、そしてロードマップでの予告という三層の防波堤が組織の摩擦を最小化します。

import { Request, Response } from 'express';

function deprecate(res: Response, sunsetISO: string, link: string) {
  res.setHeader('Deprecation', 'true');
  res.setHeader('Sunset', sunsetISO);
  res.setHeader('Link', `<${link}>; rel="deprecation"`);
}

app.get('/v1/orders', (req: Request, res: Response) => {
  deprecate(res, '2026-03-31T00:00:00Z', 'https://docs.example.com/migrate-v1-to-v2');
  res.json({ items: [] });
});

ガバナンスの面では、APIレビューをPull Requestの標準フローに統合し、アーキテクトが規約チェックを行うよりも自動化されたルールで逸脱を検知する仕組みを先に用意するとスケールします。Spectralのカスタムルールで命名規則や応答の一貫性を機械化し¹⁰、例外は明示的な許可を経てマージされるようにします。運用指標はSLOに集約し、レイテンシと可用性、エラー率、スロットリングのヒット率などをSaaSのダッシュボードで公開して、ビジネス側と同じ数字で会話できる状態を常態化させます²¹。

小さく始めて早く回すための現実的な進め方

全社変革としての大上段ではなく、ひとつのプロダクトか限定したエンドポイント群でパイロットを走らせると学習サイクルが短くなります。最小の契約を作り、モックを立て、デザインレビューで非機能まで詰める。コード生成とバリデーションをプロジェクトに組み込み、互換性チェックと負荷試験をCIに貼り付ける。ここまでを1スプリントで通すと、契約駆動のメリットと痛点が自分たちの土壌で可視化され、横展開の説得力が増します。

まとめ：契約に投資し、再作業の沼から抜け出す

APIファーストは新奇な流行ではありません。契約を先に置くという素朴な原則を、ツールチェーンと自動化で現実にするだけです。契約の粒度が十分であれば、再作業の山は低くなり、障害の初動は速まり、開発と運用の会話は噛み合います。まずは重要なユースケースをひとつ選び、OpenAPIで最小の契約を記述し、モックとコード生成を組み合わせた流れを自分たちのCIに流し込んでみてください。SLOに照らした負荷試験と互換性チェックまで到達すれば、すでに組織の学習曲線は上向いているはずです。次のスプリントの計画に、ひとつだけでも契約駆動のタスクを入れる。そこから、実感の伴う変化が始まります。

参考文献

  1. Christopher J. Westland. The cost of errors in software development: evidence from industry. Journal of Systems and Software, 2002. https://www.researchgate.net/publication/222836494_The_cost_of_errors_in_software_development_evidence_from_industry
  2. Barry W. Boehm. Software Engineering Economics. Prentice Hall, 1981.
  3. ITPro Today. Save $5,600 Per Minute by Eliminating Downtime: Tactical Tips. https://www.itprotoday.com/edge-computing/save-5-600-per-minute-by-eliminating-downtime-tactical-tips
  4. Postman. State of the API Report 2023. https://www.postman.com/state-of-api/2023/
  5. OpenAPI Initiative. OpenAPI Specification 3.0.3. https://spec.openapis.org/oas/v3.0.3
  6. AsyncAPI Initiative. AsyncAPI. https://www.asyncapi.com/
  7. OpenAPI Generator. https://openapi-generator.tech/
  8. Stoplight. Prism. https://github.com/stoplightio/prism
  9. express-openapi-validator. https://github.com/cdimascio/express-openapi-validator
  10. Stoplight. Spectral. https://github.com/stoplightio/spectral
  11. OpenAPITools. openapi-diff. https://github.com/OpenAPITools/openapi-diff
  12. RFC 7807: Problem Details for HTTP APIs. https://www.rfc-editor.org/rfc/rfc7807
  13. OpenTelemetry. JavaScript/Node.js instrumentation docs. https://opentelemetry.io/docs/instrumentation/js/
  14. Grafana k6. Thresholds. https://k6.io/docs/using-k6/thresholds/
  15. RFC 9110: HTTP Semantics. https://www.rfc-editor.org/rfc/rfc9110
  16. IETF HTTPAPI. The Idempotency-Key HTTP Header Field (Internet-Draft). https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-idempotency-key-header
  17. Pact. Documentation. https://docs.pact.io/
  18. Semantic Versioning 2.0.0. https://semver.org/
  19. RFC 8594: The Sunset HTTP Header Field. https://www.rfc-editor.org/rfc/rfc8594
  20. The Deprecation HTTP Header Field (Internet-Draft). https://datatracker.ietf.org/doc/html/draft-dalal-deprecation-header
  21. Google SRE Book. Service Level Objectives. https://sre.google/sre-book/service-level-objectives/