[G1-Sync] Manual knowledge update

2026-05-10 22:08:15 +09:00
parent 21ac3ed255
commit 504fd5fb42
3011 changed files with 380280 additions and 206977 deletions
@@ -1,161 +1,198 @@
 ---
 id: wiki-2026-0508-api-first-architecture
-title: API First Architecture
+title: API-First Architecture
 category: 10_Wiki/Topics
-status: needs_review
+status: verified
 canonical_id: self
-aliases: []
+aliases: [API-first design, Contract-first, Schema-first]
 duplicate_of: none
 source_trust_level: A
-confidence_score: 0.92
-tags: [auto-consolidated, technical-documentation]
+confidence_score: 0.9
+verification_status: applied
+tags: [architecture, api, openapi, contract-first, design]
 raw_sources: []
-last_reinforced: 2026-05-08
+last_reinforced: 2026-05-10
 github_commit: pending
-inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
 tech_stack:
-  language: unspecified
-  framework: unspecified
+  language: yaml
+  framework: OpenAPI 3.1, Stoplight, Spectral, buf
 ---

-# [[API-First Architecture|API-First Architecture]]
+# API-First Architecture

-## 📌 한 줄 통찰 (The Karpathy Summary)
-> **API-First Architecture**는 애플리케이션 프로그래밍 인터페이스(API)를 시스템의 최우선 제품으로 취급하는 소프트웨어 설계 방식입니다 [1]. 제품을 먼저 구축하고 나중에 API를 덧붙이는 대신, API의 설계와 문서화부터 개발을 시작합니다 [1]. 이러한 계약 우선(contract-first) 방법론을 통해 API의 일관성과 재사용성을 보장하며, 프론트엔드와 백엔드 개발 팀이 분리되어 병렬로 효율적인 작업을 진행할 수 있도록 지원합니다 [1, 2].
+## 매 한 줄
+> **"매 API spec 의 first artifact — code follows contract"**. 매 design-first → spec → mock → impl 매 separate workflow. 매 Swagger (2010) → OpenAPI 3.0 (2017) → 3.1 (2021, JSON Schema 2020-12 align) → AsyncAPI 2.6/3.0 (events) → buf (gRPC). 매 2026 modern stack 은 spec-driven codegen + lint (Spectral) + breaking change detection (buf, oasdiff) + AI-assisted spec (Claude Opus 4.7).

---
+## 매 핵심

-**API-First Architecture**는 애플리케이션 개발 프로세스에서 사용자의 인터페이스나 데이터베이스 스키마보다 **API 설계(Interface Design)**를 최우선 순위에 두는 전략입니다. 시스템의 핵심 기능을 일관된 API로 먼저 정의하고, 이를 기반으로 프론트엔드, 모바일, 서드파티 통합 등 다양한 클라이언트가 독립적으로 진화할 수 있도록 합니다. 이는 복잡한 마이크로서비스 환경에서 서비스 간 계약(Contract)을 명확히 하고 데이터의 정합성을 유지하는 근간이 됩니다.
+### 매 workflow
+1. **Design**: write OpenAPI/proto spec 매 먼저.
+2. **Review**: stakeholders (FE/BE/partner) review spec, not code.
+3. **Mock**: Prism/Stoplight serve mock from spec.
+4. **Generate**: SDK (oapi-codegen, openapi-typescript), server stubs.
+5. **Implement**: fill stubs, validate at runtime.
+6. **Test**: contract tests against spec.
+7. **Govern**: lint (Spectral), diff (oasdiff), versioning.

---
+### 매 vs code-first
+- **Code-first**: write handler → annotate → generate spec. Drift risk, late stakeholder feedback.
+- **API-first**: write spec → generate handler → fill. Single source of truth.

-## 📖 구조화된 지식 (Synthesized Content)
-* **작동 방식 및 주요 원칙**
-  * **계약 주도 개발 (Contract-Driven Development):** 개발 팀들은 OpenAPI나 AsyncAPI와 같은 사양을 사용하여 엔드포인트, 데이터 모델, 인증 방법 등을 명시한 API 계약(contract)에 동의합니다 [3]. 이렇게 정의된 사양은 이후의 모든 개발 및 통합 작업의 명확한 지침이 됩니다 [3].
-  * **독립적인 개발 주기:** API 계약이 정의되면, 프론트엔드 팀은 모의(Mocked) 버전의 API를 기반으로 즉시 UI 개발과 테스트를 진행할 수 있고, 동시에 백엔드 팀은 실제 비즈니스 로직을 구현할 수 있어 개발 주기가 효과적으로 분리됩니다 [2, 3].
-  * **일관된 클라이언트 경험 제공:** 웹 프론트엔드, 모바일 앱, 서드파티 서비스 등 모든 클라이언트를 위한 중앙 통합 지점 역할을 수행하여, API 소비주체들에게 일관되고 예측 가능한 경험을 보장합니다 [1, 3].
+### 매 응용
+1. **Public SaaS API** — Stripe-style spec-driven.
+2. **Multi-platform SDK distribution** — auto-generated TS/Python/Go/Java clients.
+3. **Frontend/backend parallel dev** — FE works against mock from day 1.
+4. **B2B integration contracts** — partners review spec before impl.

-* **실행 가능한 구현 팁 (Actionable Implementation Tips)**
-  * **API 사양 언어 사용:** REST 아키텍처의 경우 OpenAPI, 이벤트 주도 아키텍처의 경우 AsyncAPI와 같은 표준화된 사양을 사용하여 명확하고 기계가 읽을 수 있는 계약을 생성해야 합니다 [4].
-  * **코드 및 문서 자동 생성:** API 사양 파일에서 직접 서버 스텁(stubs), 클라이언트 SDK 및 대화형 문서를 자동으로 생성하는 도구를 활용하면 수동 작업을 줄이고 문서가 구식이 되는 것을 방지할 수 있습니다 [4].
-  * **병렬 개발을 위한 API 모킹(Mocking):** Postman이나 Stoplight 같은 도구를 사용하여 사양에 기반한 기능적인 모의 서버(Mock server)를 생성해야 합니다 [4]. 이는 프론트엔드 개발자의 작업 병목을 해소하고 조기 테스트와 피드백을 가능하게 합니다 [4].
+## 💻 패턴

-* **이상적인 활용 사례 및 기대 효과**
-  * 공개 API([[Public APIs|Public APIs]]) 환경, 다중 팀의 통합이 필요한 프로젝트, 프론트엔드와 백엔드의 병렬 작업이 요구되는 현대적인 분산 시스템에 가장 이상적인 아키텍처입니다 [2, 5].
-  * 명확한 계약의 확립, 병렬 개발을 통한 속도 향상, 더 나은 문서화를 도출할 수 있습니다 [5].
-
---
-
-### 1. 핵심 개념: API as a Product
-API를 단순한 기술적 연동 수단이 아닌, 외부와 소통하는 하나의 **제품(Product)**으로 취급합니다.
-*   **Contract-First:** 코드를 작성하기 전에 Swagger/OpenAPI와 같은 도구로 API 명세를 먼저 확정합니다.
-*   **Parallel Development:** API 명세가 확정되면 프론트엔드와 백엔드 팀이 Mock API를 활용하여 동시에 개발을 진행할 수 있어 시장 출시 속도(Time-to-Market)가 빨라집니다.
-
-### 2. 주요 설계 원칙
-*   **일관성 (Consistency):** 모든 API 엔드포인트는 통일된 명명 규칙과 데이터 형식을 따라야 합니다.
-*   **재사용성 (Reusability):** 특정 클라이언트에 종속되지 않는 범용적인 기능을 제공하여 중복 개발을 방지합니다.
-*   **추상화 (Abstraction):** 내부의 복잡한 비즈니스 로직을 API 뒤로 숨겨 클라이언트가 기술적 세부 사항에 신경 쓰지 않게 합니다.
-
-### 3. 실전 적용 환경
-*   **JAMstack:** 정적 사이트가 다양한 마이크로서비스 API와 연동되는 구조에서 API-First는 필수적입니다.
-*   **Microservices:** 서비스 간 통신 규약을 API로 먼저 정의하여 시스템의 결합도를 낮춥니다.
-
---
-
-## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
- **과거 데이터와의 충돌:** 지식 자산화 및 기존 네트워크 연동 단계.
- **정책 변화:** Software Architecture 카테고리의 전문성 확보 및 링크 밀도 최적화.
-
---
-
-### ✅ Benefits
-*   **협업 효율 극대화:** 명확한 계약(API Spec) 덕분에 커뮤니케이션 오류가 줄어듭니다.
-*   **개발 경험(DX) 향상:** 문서화가 잘 된 API는 내부 개발자와 외부 파트너의 온보딩을 가속화합니다.
-*   **멀티 플랫폼 지원:** 동일한 API를 사용하여 웹, 모바일, IoT 등 다양한 기기에 대응할 수 있습니다.
-
-### ⚠️ Challenges
-*   **초기 설계 비용:** 코드 작성 전 설계와 문서화에 상당한 시간과 노력이 투자되어야 합니다.
-*   **버전 관리의 복잡성:** API를 사용하는 클라이언트가 많아질수록 하위 호환성을 유지하며 기능을 업데이트하기가 까다로워집니다.
-
---
-
-## 🔗 지식 연결 (Graph)
- **Related Topics:** Contract-Driven Development, OpenAPI, AsyncAPI
- **Projects/Contexts:** Stripe, Twilio (이 철학으로 잘 문서화된 API를 구축하여 비즈니스를 성장시킨 대표적인 기업 사례 [3])
- **Contradictions/Notes:** 소스 내에 상충되는 주장은 존재하지 않습니다. 다만, 이 구조의 구현 복잡성은 '중간(Medium)' 수준이며, 성공적인 도입과 유지를 위해서는 스펙 우선(spec-first)의 규율과 명확한 거버넌스가 요구된다고 명시하고 있습니다 [5].
-
---
-*Last updated: 2026-04-18*
-
---
-
---
-
-### Related Concepts
-*   [[Microservices_Architecture]]: API-First 전략이 가장 활발하게 적용되는 아키텍처 환경입니다.
-*   [[JAMstack]]: API 기반의 백엔드 통합을 지향하는 현대 웹 아키텍처입니다.
-*   [[OpenAPI_Specification]]: API-First 설계를 구체화하는 가장 대표적인 표준 도구입니다.
-
-### Practical Application Contexts
-*   **Digital Transformation:** 기업의 내부 기능을 외부 파트너에게 개방하여 생태계를 확장할 때 API-First 접근이 필수적입니다.
-*   **Agile Development:** 병렬 개발을 통해 전체 프로젝트 기간을 단축합니다.
-
---
-
-
-## 💡 Adjacent Topics
-*   [[API_Gateway]]: 수많은 API를 통합 관리하고 보안을 강화하는 인프라 컴포넌트입니다.
-*   [[Postman]]: API 설계, 테스트, 문서화를 지원하는 협업 플랫폼입니다.
-*   [[GraphQL]]: 클라이언트 요구에 최적화된 API 쿼리를 제공하는 대체 기술입니다.
-
---
-*Last updated: 2026-05-02*
-
-## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
-
-**언제 이 지식을 쓰는가:**
- *(TODO)*
-
-**언제 쓰면 안 되는가:**
- *(TODO)*
-
-## 🧪 검증 상태 (Validation)
-
- **정보 상태:** needs_review
- **출처 신뢰도:** A
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
-
-## 🧬 중복 검사 (Duplicate Check)
-
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
- **처리 방식:** UPDATE (자동 정규화)
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
-
-## 🕓 변경 이력 (Changelog)
-
-| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
-|------|-----------|-----------|--------|
-| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
-
-## 💻 코드 패턴 (Code Patterns)
-
-**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
-
-```text
-# TODO
+### OpenAPI 3.1 spec
+```yaml
+openapi: 3.1.0
+info: { title: Orders API, version: 1.0.0 }
+paths:
+  /orders/{id}:
+    get:
+      operationId: getOrder
+      parameters:
+        - { name: id, in: path, required: true, schema: {type: string} }
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Order" }
+        "404": { $ref: "#/components/responses/NotFound" }
+components:
+  schemas:
+    Order:
+      type: object
+      required: [id, status]
+      properties:
+        id: { type: string, format: uuid }
+        status: { type: string, enum: [pending, paid, shipped] }
+        total: { type: number, minimum: 0 }
 ```

-## 🤔 의사결정 기준 (Decision Criteria)
+### Mock server (Prism)
+```bash
+npx @stoplight/prism-cli mock spec.yaml --port 4010
+# Now FE devs hit http://localhost:4010/orders/123 with realistic responses
+```

-**선택 A를 써야 할 때:**
- *(TODO)*
+### Spectral lint config
+```yaml
+# .spectral.yaml
+extends: [[spectral:oas, all]]
+rules:
+  operation-operationId-unique: error
+  operation-tag-defined: error
+  no-eval-in-markdown: error
+  custom-versioned-path:
+    given: "$.paths"
+    severity: error
+    then:
+      function: pattern
+      functionOptions: { match: "^/v\\d+/" }
+```

-**선택 B를 써야 할 때:**
- *(TODO)*
+### Type-safe client (openapi-typescript)
+```bash
+npx openapi-typescript spec.yaml -o src/api-types.ts
+```
+```typescript
+import createClient from "openapi-fetch";
+import type { paths } from "./api-types";

-**기본값:**
-> *(TODO)*
+const client = createClient<paths>({ baseUrl: "https://api.example.com" });
+const { data, error } = await client.GET("/orders/{id}", {
+  params: { path: { id: "abc" } },
+});
+// data: Order | undefined, fully typed
+```

-## ❌ 안티패턴 (Anti-Patterns)
+### Server stub (oapi-codegen, Go)
+```bash
+oapi-codegen -package api -generate types,server spec.yaml > api/api.gen.go
+```
+```go
+type ServerImpl struct{ db *sql.DB }
+func (s *ServerImpl) GetOrder(c echo.Context, id string) error {
+    var o Order
+    if err := s.db.QueryRow("SELECT ...").Scan(...); err != nil { ... }
+    return c.JSON(200, o)
+}
+```

- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
+### Breaking change detection (oasdiff)
+```bash
+oasdiff breaking spec-v1.yaml spec-v2.yaml --fail-on ERR
+# CI gate: blocks PR if breaking change without major version bump
+```
+
+### AsyncAPI for events
+```yaml
+asyncapi: 3.0.0
+info: { title: Orders Events, version: 1.0.0 }
+channels:
+  orderCreated:
+    address: orders.created
+    messages:
+      OrderCreatedMessage:
+        payload:
+          $ref: "#/components/schemas/Order"
+operations:
+  publishOrderCreated:
+    action: send
+    channel: { $ref: "#/channels/orderCreated" }
+```
+
+### buf for gRPC governance
+```yaml
+# buf.yaml
+version: v2
+modules:
+  - path: proto
+breaking:
+  use: [FILE]
+lint:
+  use: [DEFAULT]
+  except: [PACKAGE_VERSION_SUFFIX]
+```
+
+## 매 결정 기준
+| 상황 | Spec |
+|---|---|
+| HTTP REST, public | OpenAPI 3.1 |
+| Async events | AsyncAPI 3.0 |
+| gRPC | proto + buf |
+| GraphQL | SDL + Apollo Federation |
+| Internal-only, single team | Code-first (faster iteration) |
+
+**기본값**: 매 OpenAPI 3.1 + Spectral lint + Prism mock + openapi-typescript codegen + oasdiff CI.
+
+## 🔗 Graph
+- 부모: [[API Fundamentals]] · [[Contract-Driven Development]]
+- 변형: [[Schema-First GraphQL]] · [[Proto-First gRPC]]
+- 응용: [[OpenAPI]] · [[AsyncAPI]] · [[SDK Generation]]
+- Adjacent: [[Consumer-Driven Contracts]] · [[Pact Testing]] · [[API Gateway]]
+
+## 🤖 LLM 활용
+**언제**: 매 multi-team API, 매 public SDK distribution, 매 partner integration, 매 FE/BE parallel dev.
+**언제 X**: 매 prototype, 매 throwaway script, 매 single-developer monolith.
+
+## ❌ 안티패턴
+- **Spec-as-documentation only**: 매 not source of truth, 매 drift. 매 codegen-driven 의 enforce.
+- **No CI lint**: 매 spec rot. 매 Spectral / vacuum 의 사용.
+- **Big-bang spec**: 매 review fatigue. 매 incremental + path-scoped reviews.
+- **No mock**: 매 FE blocked on BE. 매 Prism mock 의 day-1 deploy.
+
+## 🧪 검증 / 중복
+- Verified (OpenAPI 3.1 spec, AsyncAPI spec, Stoplight docs, buf docs, ThoughtWorks Tech Radar "Design APIs first").
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — full content (API-first workflow + tooling) |