dev-api-design
Build APIs across REST, GraphQL, gRPC, and tRPC styles with contract-first design, RFC 9457 error models, and modern best practices. Covers OpenAPI specs, versioning strategies, authentication/authorization, rate limiting, pagination, and observability patterns for public and internal services.
dev-api-design helps you architect production-grade APIs using REST, GraphQL, gRPC, or tRPC with proper contracts and patterns.
AI-generated summary based on this skill's SKILL.md
Install
vasilyu1983/AI-Agents-public/dev-api-design · repository language: Python
git clone https://github.com/vasilyu1983/AI-Agents-public
cp -r AI-Agents-public/frameworks/shared-skills/skills/dev-api-design ~/.claude/skills/dev-api-designnpx skillfed install vasilyu1983/AI-Agents-public/dev-api-designFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I design a REST API?
dev-api-design teaches REST API fundamentals including resource modeling, HTTP method semantics, status codes, and contract-first approaches. The skill covers designing endpoints that follow REST principles, structuring payloads, and implementing proper HTTP semantics for CRUD operations and complex workflows.
REST vs GraphQL vs gRPC—which should I use?
dev-api-design helps you evaluate each style: REST for simple CRUD and public APIs, GraphQL for flexible client queries and reducing over-fetching, and gRPC for high-performance internal services. The skill guides tradeoffs in complexity, caching, tooling, and team expertise to match your use case.
What are the best API versioning strategies?
dev-api-design covers versioning approaches including URL paths, headers, and content negotiation, plus deprecation policies and breaking-change detection. It teaches how to plan API evolution, communicate changes to consumers, and maintain backward compatibility or manage controlled transitions.
How do I write an OpenAPI specification?
dev-api-design guides OpenAPI spec authoring for documenting REST APIs with schemas, parameters, responses, and security definitions. The skill shows how to generate interactive documentation, validate requests against specs, and use specs for code generation and contract testing.
How should I implement authentication and rate limiting?
dev-api-design covers JWT and OAuth2 authentication patterns, API key management, and rate-limiting strategies (token bucket, sliding window). It includes authorization checks, token refresh flows, and designing rate limits that protect backend resources while respecting client needs.
What error handling patterns should production APIs follow?
dev-api-design teaches RFC 9457 problem details format for structured error responses, HTTP status code semantics, and error recovery strategies. The skill covers logging errors for observability, communicating failures clearly to clients, and designing retry-safe operations.
SKILL.md
rendered from the published skill — quoted content, verbatim
API Development & Design — Quick Reference
Use this skill to design, implement, and document production-grade APIs (REST, GraphQL, gRPC, and tRPC). Apply it for contract design (OpenAPI), versioning/deprecation, authentication/authorization, rate limiting, pagination, error models, and developer documentation.
Modern best practices (Jan 2026): HTTP semantics and cacheability (RFC 9110), Problem Details error model (RFC 9457), OpenAPI 3.1+, contract-first + breaking-change detection, strong AuthN/Z boundaries, explicit versioning/deprecation, and operable-by-default APIs (idempotency, rate limits, observability, trace context).
Default Execution Checklist
- Choose an API style based on constraints (public vs internal, performance, client query flexibility).
- Define the contract first (OpenAPI or GraphQL schema; protobuf for gRPC).
- Define the error model (RFC 9457 + stable error codes + trace IDs).
- Define AuthN/AuthZ boundaries (scopes/roles/tenancy) and threat model.
- Define
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 15 files
frameworks/shared-skills/skills/dev-api-design/SKILL.md
frameworks/shared-skills/skills/dev-api-design/assets/cross-platform/api-patterns-universal.md
frameworks/shared-skills/skills/dev-api-design/assets/cross-platform/template-api-design-review-checklist.md
frameworks/shared-skills/skills/dev-api-design/assets/cross-platform/template-api-error-model.md
frameworks/shared-skills/skills/dev-api-design/assets/cross-platform/template-api-governance.md
frameworks/shared-skills/skills/dev-api-design/assets/django-rest/django-rest-complete-api.md
frameworks/shared-skills/skills/dev-api-design/assets/express-nodejs/express-complete-api.md
frameworks/shared-skills/skills/dev-api-design/assets/fastapi/fastapi-complete-api.md
frameworks/shared-skills/skills/dev-api-design/assets/openapi-template.yaml
frameworks/shared-skills/skills/dev-api-design/assets/spring-boot/spring-boot-complete-api.md
frameworks/shared-skills/skills/dev-api-design/data/sources.json
frameworks/shared-skills/skills/dev-api-design/references/api-design-best-practices.md
frameworks/shared-skills/skills/dev-api-design/references/api-security-checklist.md
frameworks/shared-skills/skills/dev-api-design/references/api-testing-patterns.md
frameworks/shared-skills/skills/dev-api-design/references/authentication-patterns.md