api-design

ashchupliak's avatarfrom ashchupliak

REST API design principles and patterns - use when designing new endpoints, creating DTOs, or planning API structure

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 8, 2025
[API Helpers]

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for REST API design, offering standardized patterns for URL structures, HTTP status codes, and request/response schemas. It serves as a definitive guide for developers to ensure consistency, scalability, and security when building or refactoring web services, helping to streamline the development of robust backend architectures.

Use Cases

  • Designing new RESTful endpoints: Utilize standardized URL structures and HTTP methods to create intuitive and predictable API paths.
  • Standardizing error handling: Implement consistent error response formats and appropriate HTTP status codes to improve API reliability and client-side debugging.
  • Planning Data Transfer Objects (DTOs): Reference structured JSON payload patterns for both single resources and paginated collections to ensure data consistency.
  • Implementing advanced query features: Apply best practices for filtering, sorting, and pagination to handle large datasets efficiently.
  • Ensuring API security and idempotency: Follow guidelines on input validation, authorization, and idempotent operations to build secure and resilient web services.
nameapi-design
descriptionREST API design principles and patterns - use when designing new endpoints, creating DTOs, or planning API structure

REST API Design Principles

URL Structure

GET    /api/v1/resources           # List all
GET    /api/v1/resources/{id}      # Get one
POST   /api/v1/resources           # Create
PUT    /api/v1/resources/{id}      # Replace
PATCH  /api/v1/resources/{id}      # Partial update
DELETE /api/v1/resources/{id}      # Delete

# Nested resources
GET    /api/v1/parents/{id}/children
POST   /api/v1/parents/{id}/children

HTTP Status Codes

Code Meaning When to Use
200 OK Successful GET, PUT, PATCH
201 Created Successful POST (new resource)
204 No Content Successful DELETE
400 Bad Request Validation errors, malformed request
401 Unauthorized Missing or invalid authentication
403 Forbidden Valid auth but no permission
404 Not Found Resource doesn't exist
409 Conflict Duplicate, state conflict
422 Unprocessable Semantic errors
500 Server Error Unexpected errors

Request/Response Design

Collection Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 150,
    "totalPages": 8
  }
}

Single Resource Response

{
  "id": "uuid",
  "name": "Resource Name",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Name is required",
    "details": [
      {"field": "name", "message": "must not be blank"}
    ]
  }
}

Query Parameters

# Filtering
GET /api/v1/resources?status=active&type=premium

# Sorting
GET /api/v1/resources?sort=createdAt,desc

# Pagination
GET /api/v1/resources?page=1&pageSize=20

# Field selection
GET /api/v1/resources?fields=id,name,status

# Search
GET /api/v1/resources?search=query

Idempotency

  • POST with unique identifiers should return existing resource (200) if duplicate
  • PUT/DELETE should be idempotent
  • Use Pair<Result, Boolean> pattern to indicate created vs existing

Versioning

  • Use URL path versioning: /api/v1/, /api/v2/
  • Version when making breaking changes
  • Support old versions during migration period

Security Considerations

  • Always validate input at API boundary
  • Use parameterized queries (JOOQ handles this)
  • Check authorization in service layer
  • Never expose internal IDs or sensitive data
  • Rate limit public endpoints