Markdown Editor
Open the editor

API Design Kit

API style guide, REST (OpenAPI 3.2), event, GraphQL and gRPC specifications, versioning and deprecation policy, plus reference and developer docs.

Step 1

Standards

  1. API Design Guidelines Template (Company Style Guide)

    Full

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

  2. API Versioning and Deprecation Policy Template

    Standard

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

    RFC 9745 (Deprecation header), RFC 8594 (Sunset header)
Step 2

Specifications

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

    Full

    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)

    Full

    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

    Full

    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)

    Standard

    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

    Full

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

Step 3

Documentation

  1. REST Endpoint Reference Template

    Standard

    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

    Standard

    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

    Full

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