api-rest-design

Apply when designing RESTful APIs, defining endpoints, HTTP methods, status codes, and response formats.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for designing high-quality, standardized RESTful APIs. It ensures consistency and scalability by guiding developers through resource naming conventions, appropriate HTTP status code selection, and standardized response formats. By adhering to industry-standard RFCs and best practices, it helps eliminate common anti-patterns like verbs in URLs or inconsistent error handling, ultimately improving the developer experience and API maintainability.

Use Cases

  • Initial API Architecture: Defining a new set of RESTful endpoints for microservices or web applications using plural nouns and proper resource nesting.
  • Standardizing Error Handling: Designing a consistent error response structure and mapping internal application errors to the correct HTTP status codes (e.g., 400, 401, 404, 422).
  • Implementing Advanced Query Features: Adding standardized filtering, sorting, and pagination to list endpoints to handle large datasets efficiently.
  • API Versioning Strategy: Planning and implementing a versioning strategy (such as URL path versioning) to ensure backward compatibility during system evolution.
  • Code Review and Quality Assurance: Using the built-in verification checklist to audit existing API designs for RESTful compliance and best practices.
nameapi-rest-design
descriptionApply when designing RESTful APIs, defining endpoints, HTTP methods, status codes, and response formats.
version1.1.0
tokens~700
confidencehigh
- https//www.rfc-editor.org/rfc/rfc9110
last_validated2025-12-10
next_review2025-12-24
tags[api, rest, backend, design]

When to Use

Apply when designing RESTful APIs, defining endpoints, HTTP methods, status codes, and response formats.

Patterns

Pattern 1: Resource Naming

# Source: https://restfulapi.net/resource-naming/
GOOD:
GET    /users              # List users
GET    /users/123          # Get user 123
POST   /users              # Create user
PUT    /users/123          # Update user 123
DELETE /users/123          # Delete user 123
GET    /users/123/orders   # User's orders (nested resource)

BAD:
GET    /getUsers           # Verb in URL
POST   /createUser         # Verb in URL
GET    /user/123           # Singular (use plural)

Pattern 2: HTTP Status Codes

# Source: https://www.rfc-editor.org/rfc/rfc9110
Success:
200 OK           - GET/PUT success with body
201 Created      - POST success, include Location header
204 No Content   - DELETE success, no body

Client Errors:
400 Bad Request  - Invalid input/payload
401 Unauthorized - Missing/invalid auth
403 Forbidden    - Auth valid, no permission
404 Not Found    - Resource doesn't exist
409 Conflict     - Resource state conflict
422 Unprocessable - Validation failed

Server Errors:
500 Internal     - Unexpected server error
503 Unavailable  - Service temporarily down

Pattern 3: Response Format

// Source: https://restfulapi.net/
// Success response
{
  "data": { "id": 123, "name": "John" },
  "meta": { "timestamp": "2025-12-10T12:00:00Z" }
}

// Error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [{ "field": "email", "message": "Must be valid email" }]
  }
}

// List with pagination
{
  "data": [...],
  "meta": { "total": 100, "page": 1, "limit": 20 }
}

Pattern 4: Filtering & Pagination

# Source: https://restfulapi.net/
GET /users?status=active&role=admin     # Filter
GET /users?sort=created_at:desc         # Sort
GET /users?page=2&limit=20              # Pagination
GET /users?fields=id,name,email         # Field selection

Pattern 5: Versioning

# Source: https://restfulapi.net/versioning/
URL path (recommended):
GET /api/v1/users

Header (alternative):
Accept: application/vnd.api+json;version=1

Anti-Patterns

  • Verbs in URLs - Use nouns: /users not /getUsers
  • Wrong status codes - Don't return 200 for errors
  • Inconsistent responses - Same format for all endpoints
  • Missing pagination - Always paginate lists
  • No versioning - Plan for API evolution

Verification Checklist

  • Resource URLs use plural nouns
  • Correct HTTP methods (GET read, POST create, etc.)
  • Appropriate status codes returned
  • Consistent error response format
  • Pagination on list endpoints
  • API versioning strategy defined