api-design-patterns

name	api-design-patterns
description	Design robust APIs with RESTful patterns, GraphQL schemas, versioning strategies, and error handling conventions. Supports OpenAPI/Swagger documentation and SDK generation patterns. Triggers on API design, schema definition, endpoint architecture, or developer experience requests.
license	MIT
complexity	intermediate
time_to_learn	30min
tags	["api","rest","graphql","openapi","design-patterns"]
inputs	["service-requirements","data-models"]
outputs	["api-specification","endpoint-design","openapi-document"]
side_effects	["creates-files"]
triggers	["user-asks-about-api","user-asks-about-rest","user-asks-about-graphql","file-type:*.openapi.yaml","project-has-openapi-spec"]
complements	["backend-implementation-patterns","mcp-builder"]
tier	core

API Design Patterns

Build APIs that developers love to use.

Design Principles

The Three Laws of API Design

1. Predictable: Consistent patterns throughout
2. Discoverable: Self-documenting, intuitive naming
3. Evolvable: Can change without breaking clients

API-First Mindset

Design → Document → Mock → Build → Test → Deploy

NOT: Build → Document (maybe) → Hope it works

---

REST Patterns

Resource Naming

# Collection
GET    /users              # List users
POST   /users              # Create user

# Item
GET    /users/{id}         # Get user
PUT    /users/{id}         # Replace user
PATCH  /users/{id}         # Update user
DELETE /users/{id}         # Delete user

# Nested resources
GET    /users/{id}/posts   # User's posts
POST   /users/{id}/posts   # Create post for user

# Actions (when CRUD doesn't fit)
POST   /users/{id}/activate
POST   /orders/{id}/cancel

Naming Conventions

Do	Don't
/users	/getUsers, /user-list
/users/{id}	/users/get/{id}
/users/{id}/posts	/getUserPosts
Plural nouns	Verbs in URLs
Lowercase, hyphens	camelCase, underscores

HTTP Methods

Method	Purpose	Idempotent	Safe
GET	Read	Yes	Yes
POST	Create	No	No
PUT	Replace	Yes	No
PATCH	Update	No*	No
DELETE	Remove	Yes	No

*PATCH can be idempotent if designed carefully

Status Codes