api-design

Design REST and GraphQL APIs with versioning, security, and OpenAPI documentation.

3|1|Updated Dec 17, 2025
One-click install
npx skills add https://github.com/ProjAnvil/MindForge --skill api-design-projanvil
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/ProjAnvil/MindForge/tree/main/skills/zh-cn/api-design
Command: npx skills add https://github.com/ProjAnvil/MindForge --skill api-design-projanvil

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

专业的 API 设计技能帮助团队建立RESTful APIs、GraphQL架构、版本控制、认证授权与文档最佳实践的统一标准,提升开发效率与系统可维护性。

Core Features & Use Cases

  • RESTful API 设计最佳实践:资源建模、URI 设计、HTTP 方法语义、错误处理与安全性。
  • GraphQL 设计与架构:schema 设计、resolver 模式、分页与联邦。
  • API 版本控制策略:URI、Header、Accept 等版本化方案及向后兼容性与变更日志。
  • 身份认证/授权与安全:OAuth2、JWT、API 密钥、RBAC/ABAC、CORS 与输入验证。
  • API 文档与开发者体验:OpenAPI/Swagger、示例、开发者门户与变更记录。
  • 实践用例:从需求分析到实现、测试、文档的一体化工作流。

Quick Start

Propose an API design for a mock domain following REST/GraphQL patterns, versioning, and security guidelines.

Frequently Asked Questions about api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design a RESTful API with proper resource modeling and endpoint semantics?

GraphQL schema design involves defining types, resolvers, and pagination patterns. This skill helps you structure schemas, implement resolver patterns, and apply federation concepts to build flexible and efficient GraphQL APIs for complex domains.

What is the best way to handle API versioning and maintain backward compatibility?

API versioning strategies include URI path, custom headers, and Accept header approaches. This skill helps you choose the right versioning method, maintain backward compatibility, and manage change logs to ensure smooth API evolution without breaking integrations.

How do I secure API authentication and authorization using OAuth2 and JWT?

Securing API authentication involves implementing OAuth2, JWT, or API keys alongside RBAC/ABAC models. This skill provides patterns for authorization, CORS configuration, and input validation to protect endpoints and enforce security best practices.

Does this API design approach support generating OpenAPI and Swagger documentation?

Yes, this approach supports generating OpenAPI and Swagger documentation. It focuses on creating comprehensive API docs, examples, and developer portals to improve developer experience and streamline service integration workflows.

When should I choose GraphQL over REST for my API architecture?

Choose GraphQL over REST when you need flexible querying to avoid over-fetching, or when managing complex nested data relationships. REST remains preferable for simple resource-based operations, caching, and standardized HTTP semantics.