api-design

name	api-design
description	RESTful, GraphQL, gRPC, and API best practices
domain	software-design
version	1.0.0
tags	["rest","graphql","grpc","websocket","openapi","versioning"]
triggers	{"keywords":{"primary":["api","rest","restful","graphql","grpc","endpoint","openapi"],"secondary":["swagger","websocket","webhook","versioning","rate limit","pagination"]},"context_boost":["backend","microservice","integration","http"],"context_penalty":["frontend","ui","css"],"priority":"high"}
collaboration	{"prerequisites":[],"delegation_triggers":[{"trigger":"Implementation of API endpoints","delegate_to":"backend","context":"Framework-specific implementation patterns"},{"trigger":"Data model for API responses","delegate_to":"database","context":"Schema design, query requirements"},{"trigger":"API contract testing","delegate_to":"testing-strategies","context":"Contract tests, integration tests"}],"receives_context_from":[{"skill":"backend","receives":["Framework capabilities","Middleware available","Authentication mechanism"]},{"skill":"database","receives":["Available data structures","Query performance characteristics"]}],"provides_context_to":[{"skill":"backend","provides":["Endpoint specifications","Request/response formats","Error code conventions"]},{"skill":"frontend","provides":["API documentation","Authentication flow","Rate limiting rules"]},{"skill":"testing-strategies","provides":["API contract specifications","Expected behaviors"]}]}

API Design

Overview

Design principles for building APIs that are intuitive, consistent, and scalable. Covers REST, GraphQL, gRPC, and real-time protocols.

---

RESTful API Design

Resource Naming

✅ Good (nouns, plural):
GET    /users           # List users
GET    /users/123       # Get user
POST   /users           # Create user
PUT    /users/123       # Update user
DELETE /users/123       # Delete user

❌ Bad (verbs, actions):
GET    /getUsers
POST   /createUser
POST   /users/123/delete

Nested Resources

# Hierarchical relationship
GET /users/123/orders              # User's orders
GET /users/123/orders/456          # Specific order

# Alternative: Query parameter for filtering
GET /orders?userId=123             # Filter orders by user

# Rule: Nest max 2 levels deep
❌ /users/123/orders/456/items/789/reviews
✅ /order-items/789/reviews

HTTP Methods & Status Codes

Method	Purpose	Success	Error
GET	Read	200	404
POST	Create	201	400, 409
PUT	Replace	200	400, 404
PATCH	Partial update	200	400, 404
DELETE	Remove	204	404

// Response structure
interface ApiResponse<T> {
  data: T;
  meta?: {
    page: number;
    limit: number;
    total: number;
  };
}

interface ApiError {
  error: {
    code: string;        // Machine-readable
    message: string;     // Human-readable
    ?: ;    
  };
}