AgentSkillsCN

rest-api-standards

RESTful API 与 OpenAPI 标准。在设计 API、编写 OpenAPI 规范、实现 REST 端点，或配置 API 文档时，可参考此标准。内容涵盖“先规范、再开发”的开发模式、版本管理、错误封装、分页机制，以及速率限制等关键特性。

SKILL.md
--- frontmatter
name: rest-api-standards
description: |
  RESTful API and OpenAPI standards. Use when designing APIs, writing OpenAPI
  specs, implementing REST endpoints, or configuring API documentation. Covers
  spec-first development, versioning, error envelopes, pagination, and rate limits.
disposition: contextual
filePatterns:
  - "**/openapi*.yml"
  - "**/openapi*.yaml"
  - "**/openapi*.json"
  - "**/api/openapi/**"
compliance:
  - soc2: CC5.2
  - iso27001: A.14.2.5
version: 1.0.0

Universal Principles

  1. •Spec-First Development – OpenAPI contract MUST be authored (or updated) before implementation code is merged.
  2. •Versioning – API major version MUST appear in the path (/api/v{major}/…) and in the info.version field.
  3. •Consistent Envelope – Error responses MUST follow { code, message, data }; success bodies SHOULD wrap data similarly.
  4. •Security Schemes – Auth MUST be declared with type: http, scheme: bearer, bearerFormat: JWT; scopes live under components/securitySchemes.
  5. •Traceability – traceparent and baggage headers MUST be documented under components/headers so clients propagate OpenTelemetry context.
  6. •Pagination – Collections SHOULD use limit / cursor parameters; responses MUST include next cursor link.
  7. •Rate Limits – Specs MUST declare 429 response and document Retry-After header semantics.
  8. •API Linting – PRs MUST pass the OpenAPI linter (spectral with company ruleset) at severity error = 0.
  9. •Example Payloads – Each schema SHOULD include at least one example; sensitive data is tokenised.
  10. •Documentation – Rendered docs (Redoc or Stoplight) MUST auto-publish on merge to main.

New Code

  1. •OpenAPI 3.0 – New APIs MUST target spec v3.0; earlier versions are prohibited.
  2. •JSON Schema $defs – Schema components SHOULD ref common $defs published by the Platform team to avoid duplication.

Existing Code

  1. •Legacy Swagger 2.0 – Existing Swagger specs MUST migrate to OpenAPI 3.0+ when touched.
  2. •Inline Definitions – While migrating, inline schema refs are permissible only if externalising would break consumers; file a debt entry.