api-design-framework

name	api-design-framework
description	Comprehensive API design patterns for REST, GraphQL, and gRPC. Use when designing APIs, creating endpoints, adding routes, implementing pagination, rate limiting, or authentication patterns.
context	fork
agent	backend-system-architect
version	1.2.0
author	AI Agent Hub
tags	["api","rest","graphql","grpc","backend","documentation"]
user-invocable	false

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

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

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