API Design Framework

This skill provides comprehensive guidance for designing robust, scalable, and developer-friendly APIs. Whether building REST, GraphQL, or gRPC services, this framework ensures consistency, usability, and maintainability.

Overview

• Designing new API endpoints or services

• Establishing API conventions for a team or organization

• Reviewing API designs for consistency and best practices

• Migrating or versioning existing APIs

• Creating API documentation (OpenAPI, AsyncAPI)

• Choosing between REST, GraphQL, or gRPC

API Design Principles

1. Developer Experience First

APIs should be intuitive and self-documenting:

• Clear, consistent naming conventions

• Predictable behavior and responses

• Comprehensive documentation

• Helpful error messages

2. Consistency Over Cleverness

Follow established patterns rather than inventing new ones:

• Standard HTTP methods and status codes (REST)

• Conventional query structures (GraphQL)

• Idiomatic proto definitions (gRPC)

3. Evolution Without Breaking Changes

Design for change from day one:

• API versioning strategy

• Backward compatibility considerations

• Deprecation policies

• Migration paths

4. Performance by Design

Consider performance implications:

• Pagination for large datasets

• Filtering and partial responses

• Caching strategies

• Rate limiting

Bundled Resources

• assets/openapi-template.yaml

• OpenAPI 3.1 specification template

• assets/asyncapi-template.yaml

• AsyncAPI specification template

• references/rest-api.md

• REST API design patterns

• references/graphql-api.md

• GraphQL API design patterns

• references/grpc-api.md

• gRPC API design patterns

• references/frontend-integration.md

• Frontend API integration patterns

Protocol References

REST API Design

See: references/rest-api.md

Key topics covered:

• Resource naming conventions (plural nouns, hierarchical relationships)

• HTTP methods (GET, POST, PUT, PATCH, DELETE)

• Status codes (2xx, 4xx, 5xx)

• Request/response formats

• Pagination (cursor-based vs offset-based)

• Filtering, sorting, field selection

• API versioning strategies

• Rate limiting headers

• Authentication patterns (Bearer, API Key)

GraphQL API Design

See: references/graphql-api.md

Key topics covered:

• Schema design principles (nullable by default)

• Connection pattern for lists (edges, nodes, pageInfo)

• Input types for mutations

• Query design patterns

• Field-level error handling

gRPC API Design

See: references/grpc-api.md

Key topics covered:

• Proto file structure

• Service and message definitions

• gRPC status codes mapping to HTTP equivalents

Frontend API Integration

See: references/frontend-integration.md

Key topics covered:

• Runtime validation with Zod

• Request interceptors with ky

• Error enrichment pattern

• TanStack Query integration

Quick Reference: HTTP Status Codes

Code Name Use Case

200 OK Successful GET, PUT, PATCH

201 Created Successful POST

204 No Content Successful DELETE

400 Bad Request Invalid request

401 Unauthorized Missing auth

403 Forbidden No permission

404 Not Found Resource missing

409 Conflict Duplicate

422 Unprocessable Validation failed

429 Too Many Requests Rate limited

500 Internal Error Server error

Quick Reference: Error Response Format

{ "error": { "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": [ { "field": "email", "message": "Email is already registered" } ], "request_id": "req_abc123" } }

Common Pitfalls

Pitfall Bad Good

Verbs in URLs POST /createUser

POST /users

Inconsistent naming /users, /userOrders

/users, /orders

Ignoring HTTP methods POST /users/123/delete

DELETE /users/123

Exposing internals /users-table

/users

Generic errors "Something went wrong"

"Email already exists"

Best Practices Summary

• Use plural nouns for resources: /users , /orders

• Use kebab-case for multi-word: /user-preferences

• Use hierarchical URLs: /users/123/orders

• Cursor pagination for large datasets

• URI versioning for public APIs: /api/v1/users

• Include rate limit headers in responses

• Validate with Zod on frontend boundary

• Include request_id in error responses

Integration with Agents

Agent Usage

backend-system-architect Designs new APIs using this framework

frontend-ui-developer Reviews contracts, integrates with APIs

code-quality-reviewer Validates API designs against standards

Related Skills

• fastapi-advanced

• FastAPI-specific implementation patterns for the API designs in this skill

• error-handling-rfc9457

• RFC 9457 Problem Details standard for structured error responses

• api-versioning

• Detailed versioning strategies beyond the basics covered here

• rate-limiting

• Advanced rate limiting implementations and algorithms

Key Decisions

Decision Choice Rationale

Pagination default Cursor-based More efficient for large datasets, stable under inserts/deletes

Error format Structured JSON with request_id Enables debugging, correlation, and consistent client handling

Versioning strategy URI path (/api/v1/ ) Most explicit, works with all clients, easy to document

Resource naming Plural nouns, kebab-case Industry standard, consistent, avoids verb confusion

Skill Version: 1.2.0 Last Updated: 2026-01-14

Changelog

v1.2.0 (2026-01-14)

• Split into reference files for progressive loading

• Added references/rest-api.md

• Added references/graphql-api.md

• Added references/grpc-api.md

• Added references/frontend-integration.md

• Fixed malformed YAML frontmatter

v1.1.0 (2025-12-29)

• Added Frontend API Integration section

• Added Zod runtime validation patterns

• Added request interceptors with ky

• Added TanStack Query integration examples

Capability Details

rest-design

Keywords: rest, restful, http, endpoint, route, path, resource, CRUD Solves:

• How do I design RESTful APIs?

• REST endpoint patterns and conventions

• HTTP methods and status codes

• API versioning and pagination

graphql-design

Keywords: graphql, schema, query, mutation, connection, relay Solves:

• How do I design GraphQL APIs?

• Schema design best practices

• Connection pattern for pagination

grpc-design

Keywords: grpc, protobuf, proto, rpc, streaming Solves:

• How do I design gRPC services?

• Proto file structure

• gRPC status codes

endpoint-design

Keywords: endpoint, route, path, resource, CRUD Solves:

• How do I structure API endpoints?

• What's the best URL pattern for this resource?

• RESTful endpoint naming conventions

pagination

Keywords: pagination, paginate, paging, offset, cursor, limit Solves:

• How do I add pagination to an endpoint?

• Cursor vs offset pagination

• Pagination best practices

versioning

Keywords: version, v1, v2, api version, breaking change Solves:

• How do I version my API?

• When to create a new API version

• URL vs header versioning

error-handling

Keywords: error, exception, status code, error response, validation error Solves:

• How do I structure error responses?

• Which HTTP status codes to use

• Error message best practices

rate-limiting

Keywords: rate limit, throttle, quota, requests per second, 429 Solves:

• How do I implement rate limiting?

• Rate limit headers and responses

• Tiered rate limiting strategies

authentication

Keywords: auth, authentication, bearer, jwt, oauth, api key Solves:

• How do I secure API endpoints?

• JWT vs API key authentication

• OAuth2 flow for APIs

frontend-integration

Keywords: zod, validation, fetch, ky, tanstack, react-query Solves:

• How do I consume APIs with type safety?

• Runtime validation of API responses

• Request interceptors and error handling