ストーリー

Platform APIのアーキテクチャ

レイヤー構成

Platform API アーキテクチャ:

┌──────────────────────────────────┐
│           Clients                │
│  Webポータル │ CLI │ Slackボット │ CI/CD │
└──────────┬───────────────────────┘
           │
┌──────────▼───────────────────────┐
│       API Gateway                │
│  認証 │ レート制限 │ ログ │ CORS  │
└──────────┬───────────────────────┘
           │
┌──────────▼───────────────────────┐
│     Platform API                 │
│  ┌─────────┬─────────┬─────────┐ │
│  │Catalog  │Resource │Template │ │
│  │API      │API      │API      │ │
│  └────┬────┴────┬────┴────┬────┘ │
│       │         │         │      │
│  ┌────▼────┬────▼────┬────▼────┐ │
│  │Approval │Provision│Audit    │ │
│  │Engine   │Engine   │Logger   │ │
│  └─────────┴─────────┴─────────┘ │
└──────────┬───────────────────────┘
           │
┌──────────▼───────────────────────┐
│     Infrastructure Adapters      │
│  Terraform │ Kubernetes │ GitHub │
│  Vault     │ Datadog    │ AWS    │
└──────────────────────────────────┘

API設計の原則

Platform APIの設計

リソースAPI

# リソースライフサイクル API

# カタログの一覧取得
GET /api/v1/catalog
  Response: { items: [{ name, category, description, parameters }] }

# リソースの作成（非同期）
POST /api/v1/resources
  Body: {
    catalog_item: "postgresql-database",
    parameters: { service_name: "payment-db", size: "medium", env: "production" }
  }
  Response: 202 Accepted
  { resource_id: "res-xxxxx", status: "pending_approval", approval_url: "..." }

# リソースのステータス確認
GET /api/v1/resources/{resource_id}
  Response: {
    resource_id: "res-xxxxx",
    status: "provisioning",  # pending_approval | approved | provisioning | ready | failed
    progress: 65,
    estimated_completion: "2026-03-04T10:05:00Z"
  }

# リソースの一覧取得（自チームのリソース）
GET /api/v1/resources?team=payment-team&env=production
  Response: { resources: [...], total: 15 }

# リソースの削除
DELETE /api/v1/resources/{resource_id}
  Response: 202 Accepted
  { status: "deleting" }

非同期操作パターン

非同期プロビジョニングの流れ:

1. クライアント → POST /api/v1/resources
2. API → 202 Accepted { resource_id, status: "pending_approval" }
3. 承認エンジンが通知 → Slack / メール
4. 承認者が承認
5. クライアント → GET /api/v1/resources/{id}
6. API → { status: "provisioning", progress: 30 }
7. プロビジョニング完了
8. クライアント → GET /api/v1/resources/{id}
9. API → { status: "ready", connection_details: {...} }

Webhook通知:
  状態が変わるたびにWebhookで通知可能
  POST /api/v1/webhooks
  { url: "https://slack.com/...", events: ["resource.ready", "resource.failed"] }

Kubernetes Operatorパターン

Custom Resource Definition（CRD）によるAPI拡張

# Platform CRD: データベースリクエスト
apiVersion: platform.cloudops.io/v1alpha1
kind: DatabaseRequest
metadata:
  name: payment-db
  namespace: payment-team
  labels:
    team: payment-team
    environment: production
spec:
  engine: postgresql
  version: "15"
  size: medium
  backup:
    enabled: true
    retention: 30
  monitoring:
    enabled: true
    slo_target: 99.9
status:
  phase: Ready          # Pending | Provisioning | Ready | Failed
  host: payment-db.internal.cloudops.io
  port: 5432
  secretRef: payment-db-credentials
  createdAt: "2026-03-04T09:00:00Z"
  cost:
    monthly: "$200"

Operatorの処理フロー

Kubernetes Operator パターン:

1. 開発者が DatabaseRequest CRD を apply
      ↓
2. Platform Operator が検知（Watch）
      ↓
3. バリデーション
   ├── パラメータ検証
   ├── RBAC チェック
   ├── コスト上限チェック
   └── ガードレール適用
      ↓
4. プロビジョニング
   ├── Terraform 実行（RDS作成）
   ├── シークレット生成（Vault）
   ├── モニタリング設定（Datadog）
   └── バックアップ設定
      ↓
5. ステータス更新
   └── status.phase = Ready
      ↓
6. 継続的な調整（Reconciliation）
   ├── ヘルスチェック
   ├── コスト追跡
   └── ドリフト検出・修正

APIのセキュリティと運用

認証・認可

APIのメトリクス

「Platform APIの可用性が99.9%を下回ると、全開発者の生産性に影響する。プラットフォームは社内の最重要サービスだ」 — 田中VPoE

まとめ

チェックリスト

• API-Firstの設計原則を説明できる
• Platform APIのレイヤー構成を理解した
• 非同期プロビジョニングパターンを設計できる
• Kubernetes OperatorによるCRDパターンを理解した

次のステップへ

次は「Kubernetesプラットフォーム抽象化」を学びます。Kubernetesの複雑さを開発者から隠蔽する方法を身につけましょう。

推定読了時間: 30分