api-design

Design RESTful APIs following conventions with proper error handling, versioning, and documentation. Use when creating or modifying API endpoints.

⭐21stars🔀15forks📁View on GitHub🕐Updated Jan 7, 2026⬇️2downloads

When & Why to Use This Skill

This Claude skill facilitates the design of robust, standardized RESTful APIs by enforcing industry-best practices for HTTP methods, URL structuring, error handling, and versioning. It serves as a comprehensive architectural guide for developers to ensure consistency, scalability, and high-quality documentation throughout the API development lifecycle.

Use Cases

  • Architecting new RESTful API endpoints with precise HTTP method mapping and resource-oriented URL patterns.
  • Standardizing error response formats across microservices to improve frontend-backend integration and debugging efficiency.
  • Implementing scalable API versioning strategies (URL-based or Header-based) to maintain backward compatibility during system upgrades.
  • Generating structured API documentation and templates that follow established REST conventions for better developer experience.
nameapi-design
descriptionDesign RESTful APIs following conventions with proper error

API Design Skill

Purpose

Create consistent, well-designed APIs.

REST Conventions

Reference: standards/rest-conventions.md

HTTP Methods

Method Use Case Idempotent
GET Retrieve resource Yes
POST Create resource No
PUT Replace resource Yes
PATCH Partial update No
DELETE Remove resource Yes

URL Patterns

GET    /users           # List users
GET    /users/:id       # Get user
POST   /users           # Create user
PUT    /users/:id       # Replace user
PATCH  /users/:id       # Update user
DELETE /users/:id       # Delete user

GET    /users/:id/posts # Nested resource

Response Status Codes

Code Meaning Use When
200 OK Successful GET, PUT, PATCH
201 Created Successful POST
204 No Content Successful DELETE
400 Bad Request Validation error
401 Unauthorized Auth required
403 Forbidden Auth insufficient
404 Not Found Resource doesn't exist
422 Unprocessable Business rule violation
500 Server Error Unexpected error

Error Response Format

Reference: standards/error-responses.md

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Versioning

Reference: standards/versioning.md

Options:

  • URL: /api/v1/users
  • Header: Accept: application/vnd.api.v1+json

Recommendation: URL versioning for simplicity

Endpoint Documentation

Use template: templates/endpoint-doc.md