Markdown Editor
에디터 열기

API 설계 키트

API 스타일 가이드, REST(OpenAPI 3.2)·이벤트·GraphQL·gRPC 명세, 버전 관리와 지원 중단 정책, 레퍼런스와 개발자 문서.

1단계

표준

  1. API Design Guidelines Template (Company Style Guide)

    전체

    Company API style guide: naming, methods, status codes, RFC 9457 errors, pagination, versioning, security, webhooks, governance

  2. API Versioning and Deprecation Policy Template

    표준

    API lifecycle policy: versioning scheme, compatibility promises, breaking changes, timelines, Deprecation and Sunset headers

    RFC 9745 (Deprecation header), RFC 8594 (Sunset header)
2단계

명세

  1. REST API Specification Template (OpenAPI 3.2, RFC 9457)

    전체

    HTTP/JSON API contract: auth, conventions, QUERY, streaming, pagination, RFC 9457 errors, endpoints, webhooks, OpenAPI 3.2 skeleton

    OpenAPI 3.1, RFC 9110, RFC 9457

  2. Event-Driven API Specification Template (AsyncAPI 3)

    전체

    Async event contract: brokers, channels, operations, CloudEvents envelope, ordering, delivery, DLQ, schema evolution, AsyncAPI YAML

    AsyncAPI 3.0, CloudEvents 1.0

  3. GraphQL Schema Specification Template

    전체

    GraphQL API spec: types, queries, mutations, subscriptions, connections, nullability, errors, auth, cost limits, federation

    GraphQL specification (September 2025 edition)

  4. gRPC Service Specification Template (Protocol Buffers)

    표준

    gRPC service spec: .proto contract, package versioning, field compatibility, google.rpc errors, deadlines, retries, streaming

    gRPC and Protocol Buffers documentation

  5. Interface Control Document (ICD) Template

    전체

    ICD between two systems – parties, requirements allocation, data element table, protocol sequence, errors, security, timing, change control

3단계

문서화

  1. REST Endpoint Reference Template

    표준

    One REST endpoint: auth, parameter tables, request example, responses per status, RFC 9457 errors, limits, idempotency, paging

    OpenAPI, RFC 9457

  2. API Overview and Getting Started Template

    표준

    API landing page – what it does, base URLs, auth in 3 steps, first request, key resources, errors, limits, next steps

  3. Developer and SDK Guide Template

    전체

    Developer guide – setup, auth, multi-language quick start, errors, pagination, rate limits, webhooks, sandbox, versioning