api-design

仓库创建 2025年12月9日最近提交 10 天前SkillHot 收录 21 天前

▸ 精选理由

覆盖多种协议与契约优先流程，便于构建清晰可维护的接口。

这个 Skill 做什么

提供 REST/GraphQL/gRPC 的设计与版本管理最佳实践。

提供 REST/GraphQL/gRPC 的接口设计与版本管理实用建议，包含契约优先、OpenAPI 文档规范、GraphQL Federation 与 gRPC 流式设计等要点。适合在定义 API 合约、规划版本策略或优化分页与错误格式时参考。强调可落地的规范（如幂等性、游标分页、标准错误格式），帮助开发与运维达成一致。

▸ 展开 SKILL.md 英文原文

REST/GraphQL/gRPC API design best practices. Use when designing APIs, defining contracts, handling versioning. Covers OpenAPI 3.2, GraphQL Federation, gRPC streaming.

开发编程API 设计OpenAPI最佳实践通用

240

Stars

Forks

仓库内 Skill

7 日增星

安装 / 使用

给你的 Agent 一句话（通用）

帮我安装这个 skill：https://raw.githubusercontent.com/majiayu000/spellbook/main/skills/api-design/SKILL.md

或 curl 直取 SKILL.md

curl -fsSL "https://raw.githubusercontent.com/majiayu000/spellbook/main/skills/api-design/SKILL.md"

SKILL.MD 节选查看完整文件 ↗

# API Design

## Core Principles

- **Contract-First** — Define API spec before implementation
- **OpenAPI 3.2** — Use OpenAPI for REST API documentation
- **URL Versioning** — Version in path `/v1/`, with Sunset headers
- **Idempotency** — PUT/DELETE must be idempotent, POST uses Idempotency-Key
- **Cursor Pagination** — Avoid offset-based pagination
- **RFC 7807 Errors** — Standard Problem Details format
- **No backwards compatibility** — Delete, don't deprecate

---

## Quick Reference

### When to Use What

| Scenario | Choice | Reason |
|----------|--------|--------|
| Public API / MVP | REST | Simple, universal, easy debugging |
| Frontend-driven / Mobile | GraphQL | Fetch exactly what

via SKILL·HOT · 数据来自 GitHub 公开信息 · 原文版权归作者所有