API Design Framework

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

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

---

Best Practices Summary

1. Use plural nouns for resources: /​users, /​orders
2. Use kebab-case for multi-word: /​user-preferences
3. Use hierarchical URLs: /​users/​123/​orders
4. Cursor pagination for large datasets
5. URI versioning for public APIs: /​api/​v1/​users
6. Include rate limit headers in responses
7. Validate with Zod on frontend boundary
8. Include request_id in error responses

---

Integration with Agents

---

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

---

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