MadAppGang API Design Patterns
Overview
RESTful and GraphQL API design patterns for building robust backend services.
REST API Design
Resource Naming
| Pattern | Example | Description |
|---|---|---|
| Plural nouns | /users, /orders |
Collections |
| Nested resources | /users/{id}/orders |
Sub-resources |
| No verbs in URLs | /users not /getUsers |
Actions via HTTP methods |
| Lowercase, hyphens | /order-items |
Consistent casing |
HTTP Methods
| Method | Purpose | Idempotent | Example |
|---|---|---|---|
| GET | Read | Yes | GET /users/123 |
| POST | Create | No | POST /users |
| PUT | Replace | Yes | PUT /users/123 |
| PATCH | Update | Yes | PATCH /users/123 |
| DELETE | Remove | Yes | DELETE /users/123 |
Status Codes
| Code | Meaning | Usage |
|---|---|---|
| 200 | OK | Successful GET/PUT/PATCH |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Validation error |
| 401 | Unauthorized | Missing/invalid auth |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 409 | Conflict | Duplicate/conflict |
| 422 | Unprocessable | Semantic error |
| 500 | Server Error | Unexpected error |
Request/Response Format
// Successful response
{
"data": {
"id": "123",
"name": "John Doe",
"email": "john@example.com"
},
"meta": {
"requestId": "req_abc123"
}
}
// Error response
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid email format",
"details": [
{
"field": "email",
"message": "Must be a valid email address"
}
]
},
"meta": {
"requestId": "req_abc123"
}
}
// List response
{
"data": [
{ "id": "1", "name": "User 1" },
{ "id": "2", "name": "User 2" }
],
"pagination": {
"total": 100,
"page": 1,
"pageSize": 20,
"totalPages": 5
}
}
Pagination
Offset Pagination
GET /users?page=2&pageSize=20
{
"data": [...],
"pagination": {
"total": 100,
"page": 2,
"pageSize": 20,
"totalPages": 5
}
}
Cursor Pagination
Better for large datasets and real-time data.
GET /users?cursor=abc123&limit=20
{
"data": [...],
"pagination": {
"nextCursor": "def456",
"prevCursor": "xyz789",
"hasMore": true
}
}
Filtering and Sorting
Query Parameters
GET /users?status=active&role=admin # Filtering
GET /users?sort=name&order=asc # Sorting
GET /users?fields=id,name,email # Field selection
GET /users?search=john # Search
Complex Filters
GET /orders?created_gte=2024-01-01&created_lte=2024-12-31
GET /products?price_min=10&price_max=100
GET /users?tags=premium,verified
Versioning
URL Versioning (Recommended)
/api/v1/users
/api/v2/users
Header Versioning
GET /users
Accept: application/vnd.api+json; version=2
Authentication
Bearer Token
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
API Key
X-API-Key: your-api-key
// or in query param (less secure)
GET /users?api_key=your-api-key
Rate Limiting
Response Headers
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200
429 Response
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"retryAfter": 60
}
}
Endpoint Examples
User CRUD
POST /api/v1/users # Create user
GET /api/v1/users # List users
GET /api/v1/users/:id # Get user
PUT /api/v1/users/:id # Replace user
PATCH /api/v1/users/:id # Update user
DELETE /api/v1/users/:id # Delete user
# Nested resources
GET /api/v1/users/:id/orders # User's orders
POST /api/v1/users/:id/orders # Create order for user
Actions (RPC-style)
For non-CRUD operations, use verbs as sub-resources:
POST /api/v1/users/:id/activate
POST /api/v1/orders/:id/cancel
POST /api/v1/payments/:id/refund
GraphQL Patterns
Schema Design
type User {
id: ID!
name: String!
email: String!
orders: [Order!]!
}
type Query {
user(id: ID!): User
users(filter: UserFilter, pagination: Pagination): UserConnection!
}
type Mutation {
createUser(input: CreateUserInput!): User!
updateUser(id: ID!, input: UpdateUserInput!): User!
deleteUser(id: ID!): Boolean!
}
input UserFilter {
status: UserStatus
role: UserRole
search: String
}
input Pagination {
first: Int
after: String
last: Int
before: String
}
Error Handling
type MutationResult {
success: Boolean!
errors: [Error!]
user: User
}
type Error {
code: String!
message: String!
field: String
}
type Mutation {
createUser(input: CreateUserInput!): MutationResult!
}
API Documentation
OpenAPI (Swagger)
openapi: 3.0.0
info:
title: User API
version: 1.0.0
paths:
/users:
get:
summary: List users
parameters:
- name: page
in: query
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
components:
schemas:
User:
type: object
properties:
id:
type: string
name:
type: string
Best Practices
1. Consistency
- Same response format across all endpoints
- Consistent naming conventions
- Predictable behavior
2. Error Messages
- Clear, actionable messages
- Include error codes for programmatic handling
- Don't expose internal details
3. Idempotency
- Support idempotency keys for POST requests
- Safe to retry without side effects
POST /orders
Idempotency-Key: unique-request-id-123
4. HATEOAS (Hypermedia)
Include links to related resources:
{
"data": {
"id": "123",
"name": "John"
},
"links": {
"self": "/users/123",
"orders": "/users/123/orders"
}
}
API design patterns for RESTful and GraphQL services