Markdown Editor
Mở trình soạn thảo

Bộ mẫu thiết kế API

Hướng dẫn thiết kế API, đặc tả REST (OpenAPI 3.2), sự kiện, GraphQL và gRPC, chính sách phiên bản và ngừng hỗ trợ, cùng tài liệu tham chiếu cho lập trình viên.

Bước 1

Chuẩn chung

  1. API Design Guidelines Template (Company Style Guide)

    Đầy đủ

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

  2. API Versioning and Deprecation Policy Template

    Chuẩn

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

    RFC 9745 (Deprecation header), RFC 8594 (Sunset header)
Bước 2

Đặc tả

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

    Đầy đủ

    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)

    Đầy đủ

    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

    Đầy đủ

    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)

    Chuẩn

    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

    Đầy đủ

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

Bước 3

Tài liệu

  1. REST Endpoint Reference Template

    Chuẩn

    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

    Chuẩn

    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

    Đầy đủ

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