7장: 플랫폼 API 설계

Level 3: 워크플로우 API (최고 수준 추상화)
  - "새 마이크로서비스 생성" (한 번의 호출로 모든 것 완료)
  - "서비스를 production에 배포" (복잡한 과정을 한 번에)
 
Level 2: 리소스 API (중간 수준 추상화)
  - "PostgreSQL 데이터베이스 생성"
  - "Redis 캐시 생성"
  - "네임스페이스 생성"
 
Level 1: 기반 API (최저 수준 추상화)
  - "Terraform 워크스페이스 실행"
  - "Kubernetes 매니페스트 적용"
  - "ArgoCD 앱 동기화"

openapi: 3.1.0
info:
  title: "Platform API"
  version: "1.0.0"
  description: "내부 개발자 플랫폼 API"
 
paths:
  /api/v1/services:
    post:
      summary: "새 서비스 생성"
      description: "Golden Path 기반으로 새 마이크로서비스를 생성합니다."
      tags: [services]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [name, template, owner]
              properties:
                name:
                  type: string
                  pattern: "^[a-z][a-z0-9-]*$"
                  example: "checkout-service"
                template:
                  type: string
                  enum: ["spring-boot", "go-grpc", "fastapi", "nextjs"]
                owner:
                  type: string
                  example: "team-checkout"
                system:
                  type: string
                  example: "checkout-system"
                options:
                  type: object
                  properties:
                    database:
                      type: string
                      enum: ["postgresql", "mysql", "none"]
                    messaging:
                      type: string
                      enum: ["kafka", "rabbitmq", "none"]
      responses:
        "202":
          description: "서비스 생성이 시작되었습니다."
          content:
            application/json:
              schema:
                type: object
                properties:
                  taskId:
                    type: string
                    example: "task-abc123"
                  status:
                    type: string
                    example: "provisioning"
                  estimatedTime:
                    type: string
                    example: "5-10 minutes"
 
  /api/v1/services/{name}:
    get:
      summary: "서비스 상세 조회"
      tags: [services]
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "서비스 상세 정보"
 
  /api/v1/infrastructure/databases:
    post:
      summary: "데이터베이스 프로비저닝"
      tags: [infrastructure]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [name, engine, size]
              properties:
                name:
                  type: string
                engine:
                  type: string
                  enum: ["postgresql", "mysql"]
                size:
                  type: string
                  enum: ["small", "medium", "large"]
                environment:
                  type: string
                  enum: ["dev", "staging", "production"]
      responses:
        "202":
          description: "데이터베이스 프로비저닝이 시작되었습니다."
 
  /api/v1/costs/{service}:
    get:
      summary: "서비스별 비용 조회"
      tags: [costs]
      parameters:
        - name: service
          in: path
          required: true
          schema:
            type: string
        - name: period
          in: query
          schema:
            type: string
            enum: ["7d", "30d", "90d"]
            default: "30d"
      responses:
        "200":
          description: "비용 데이터"

import { Router, Request, Response } from 'express';
import { z } from 'zod';
import { ScaffolderClient } from '../clients/scaffolder';
import { AuditLogger } from '../audit/logger';
import { CostEstimator } from '../costs/estimator';
 
const CreateServiceSchema = z.object({
  name: z.string().regex(/^[a-z][a-z0-9-]*$/),
  template: z.enum(['spring-boot', 'go-grpc', 'fastapi', 'nextjs']),
  owner: z.string(),
  system: z.string().optional(),
  options: z.object({
    database: z.enum(['postgresql', 'mysql', 'none']).default('none'),
    messaging: z.enum(['kafka', 'rabbitmq', 'none']).default('none'),
  }).optional(),
});
 
const router = Router();
 
router.post('/api/v1/services', async (req: Request, res: Response) => {
  // 입력 검증
  const parsed = CreateServiceSchema.safeParse(req.body);
  if (!parsed.success) {
    return res.status(400).json({
      error: 'Validation failed',
      details: parsed.error.issues,
    });
  }
 
  const input = parsed.data;
  const userId = req.user?.id;
 
  // 비용 추정
  const costEstimate = await CostEstimator.estimate({
    template: input.template,
    database: input.options?.database,
    messaging: input.options?.messaging,
  });
 
  // Scaffolder 작업 실행
  const task = await ScaffolderClient.createTask({
    templateRef: `template:default/${input.template}-service`,
    values: {
      serviceName: input.name,
      owner: input.owner,
      system: input.system,
      database: input.options?.database,
      messaging: input.options?.messaging,
    },
    createdBy: userId,
  });
 
  // 감사 로그 기록
  await AuditLogger.log({
    action: 'service.create',
    actor: userId,
    resource: input.name,
    details: {
      template: input.template,
      options: input.options,
      estimatedMonthlyCost: costEstimate.monthly,
    },
  });
 
  return res.status(202).json({
    taskId: task.id,
    status: 'provisioning',
    estimatedTime: '5-10 minutes',
    estimatedMonthlyCost: costEstimate.monthly,
    statusUrl: `/api/v1/tasks/${task.id}`,
  });
});
 
export { router as servicesRouter };

import { Request, Response, NextFunction } from 'express';
import { verifyToken } from '../auth/oidc';
 
interface PlatformUser {
  id: string;
  email: string;
  groups: string[];
  roles: string[];
}
 
declare global {
  namespace Express {
    interface Request {
      user?: PlatformUser;
    }
  }
}
 
export async function authMiddleware(
  req: Request,
  res: Response,
  next: NextFunction,
) {
  const token = req.headers.authorization?.replace('Bearer ', '');
 
  if (!token) {
    return res.status(401).json({ error: 'Authentication required' });
  }
 
  try {
    const payload = await verifyToken(token);
    req.user = {
      id: payload.sub,
      email: payload.email,
      groups: payload.groups || [],
      roles: payload.roles || [],
    };
    next();
  } catch (error) {
    return res.status(401).json({ error: 'Invalid token' });
  }
}

roles:
  developer:
    permissions:
      - action: "service.create"
        conditions:
          owner: "self-team"
      - action: "infrastructure.request"
        conditions:
          environment: ["dev", "staging"]
          estimatedCost:
            lessThan: 200
      - action: "service.read"
      - action: "cost.read"
        conditions:
          scope: "own-team"
 
  team-lead:
    inherits: developer
    permissions:
      - action: "infrastructure.request"
        conditions:
          environment: ["dev", "staging", "production"]
          estimatedCost:
            lessThan: 1000
      - action: "infrastructure.approve"
        conditions:
          team: "own-team"
      - action: "cost.read"
        conditions:
          scope: "own-team"
 
  platform-admin:
    permissions:
      - action: "*"

interface AuditEvent {
  action: string;
  actor: string | undefined;
  resource: string;
  details: Record<string, unknown>;
  result?: 'success' | 'failure';
  reason?: string;
}
 
export class AuditLogger {
  static async log(event: AuditEvent): Promise<void> {
    const auditRecord = {
      timestamp: new Date().toISOString(),
      ...event,
      metadata: {
        apiVersion: 'v1',
        source: 'platform-api',
      },
    };
 
    // 구조화된 로그로 출력
    console.log(JSON.stringify(auditRecord));
 
    // 영구 저장소에 기록 (예: Elasticsearch)
    await AuditStore.write(auditRecord);
  }
}

# 새 서비스 생성
platform create service checkout-service \
  --template spring-boot \
  --owner team-checkout \
  --database postgresql
 
# 서비스 목록 조회
platform list services --team team-checkout
 
# 서비스 상태 확인
platform status checkout-service
 
# 데이터베이스 프로비저닝
platform create database checkout-db \
  --engine postgresql \
  --size medium \
  --environment dev
 
# 비용 조회
platform cost checkout-service --period 30d
 
# 환경 전환
platform env switch staging
 
# 로그 조회
platform logs checkout-service --tail 100

package main
 
import (
	"fmt"
	"os"
 
	"github.com/spf13/cobra"
)
 
var rootCmd = &cobra.Command{
	Use:   "platform",
	Short: "내부 개발자 플랫폼 CLI",
	Long:  "IDP의 모든 기능을 커맨드라인에서 사용할 수 있습니다.",
}
 
var createServiceCmd = &cobra.Command{
	Use:   "service [name]",
	Short: "새 서비스 생성",
	Args:  cobra.ExactArgs(1),
	RunE: func(cmd *cobra.Command, args []string) error {
		name := args[0]
		template, _ := cmd.Flags().GetString("template")
		owner, _ := cmd.Flags().GetString("owner")
		database, _ := cmd.Flags().GetString("database")
 
		fmt.Printf("Creating service: %s\n", name)
		fmt.Printf("  Template: %s\n", template)
		fmt.Printf("  Owner: %s\n", owner)
		fmt.Printf("  Database: %s\n", database)
 
		// Platform API 호출
		client := NewPlatformClient()
		result, err := client.CreateService(CreateServiceInput{
			Name:     name,
			Template: template,
			Owner:    owner,
			Options: ServiceOptions{
				Database: database,
			},
		})
		if err != nil {
			return fmt.Errorf("service creation failed: %w", err)
		}
 
		fmt.Printf("\nService creation started!\n")
		fmt.Printf("  Task ID: %s\n", result.TaskID)
		fmt.Printf("  Status: %s\n", result.StatusURL)
 
		return nil
	},
}
 
func init() {
	createCmd := &cobra.Command{
		Use:   "create",
		Short: "리소스 생성",
	}
 
	createServiceCmd.Flags().String("template", "spring-boot", "서비스 템플릿")
	createServiceCmd.Flags().String("owner", "", "소유 팀")
	createServiceCmd.Flags().String("database", "none", "데이터베이스 유형")
	_ = createServiceCmd.MarkFlagRequired("owner")
 
	createCmd.AddCommand(createServiceCmd)
	rootCmd.AddCommand(createCmd)
}
 
func main() {
	if err := rootCmd.Execute(); err != nil {
		os.Exit(1)
	}
}

/api/v1/services        # 현재 안정 버전
/api/v2/services        # 차기 버전 (베타)
/api/v1/infrastructure  # 현재 안정 버전