REST API Design

REST API Design

Design RESTful APIs with proper conventions and developer experience.

Resource Naming

# Good - nouns, plural, hierarchical
GET    /api/users
GET    /api/users/123
GET    /api/users/123/orders
POST   /api/users
PATCH  /api/users/123
DELETE /api/users/123

# Bad - verbs, actions in URL
GET    /api/getUsers
POST   /api/createUser
POST   /api/users/123/delete

HTTP Methods

| Method | Purpose | Idempotent |

|--------|---------|------------|

| GET | Read resource | Yes |

| POST | Create resource | No |

| PUT | Replace resource | Yes |

| PATCH | Partial update | Yes |

| DELETE | Remove resource | Yes |

Status Codes

| Code | Meaning | Use For |

|------|---------|---------|

| 200 | OK | Successful GET, PATCH |

| 201 | Created | Successful POST |

| 204 | No Content | Successful DELETE |

| 400 | Bad Request | Validation errors |

| 401 | Unauthorized | Missing auth |

| 403 | Forbidden | Insufficient permissions |

| 404 | Not Found | Resource doesn't exist |

| 429 | Too Many Requests | Rate limited |

Response Format

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John",
      "email": "[email protected]"
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Collection Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  },
  "links": {
    "self": "/api/users?page=1",
    "next": "/api/users?page=2"
  }
}

Query Parameters

GET /api/products?category=electronics    # Filtering
GET /api/products?sort=-price,name        # Sorting
GET /api/products?page=2&limit=20         # Pagination
GET /api/products?fields=id,name,price    # Field selection

Best Practices

• Use nouns for resources, not verbs
• Version API via URL path (/api/v1/)
• Return appropriate status codes
• Include pagination for collections
• Document with OpenAPI/Swagger