api-design_skill

Overview

This skill delivers practical guidance for designing RESTful APIs using widely adopted conventions and industry best practices. It focuses on resource-oriented design, clear URL structure, consistent response formats, and robust error handling. The guidance is language-agnostic but uses examples that map easily to Java-based backends. It helps teams produce predictable, maintainable, and versioned APIs.

How this skill works

The skill inspects API design decisions and recommends patterns: noun-based resource naming, correct HTTP method usage, and logical URL hierarchies. It defines response and error formats (JSON, camelCase fields, metadata) and maps common operations to appropriate status codes. It also recommends operational considerations like pagination, rate limiting, and OpenAPI documentation to make APIs discoverable and reliable.

When to use it

• When designing new REST APIs for web or mobile clients
• When refactoring or standardizing existing endpoints across services
• When introducing API versioning or public endpoints
• When writing API documentation or OpenAPI specifications
• When defining error and response contracts for client teams

Best practices

• Design around resources (use nouns) and let HTTP methods express actions
• Use consistent URL patterns and include versioning in the path (e.g., /api/v1/)
• Return JSON with predictable field naming (camelCase) and include metadata for lists
• Use appropriate status codes (201 for created, 400 for bad requests, 404 for missing resources)
• Provide structured error payloads with code, message, and optional details
• Apply pagination, rate limiting, and document APIs with OpenAPI/Swagger

Example use cases

• Designing CRUD endpoints for a user or product service with predictable URIs
• Standardizing error responses for a microservices ecosystem to simplify client handling
• Creating paginated list endpoints for large datasets (e.g., /api/v1/products?page=2&size=50)
• Documenting and publishing an OpenAPI spec to enable client code generation
• Implementing partial updates with PATCH and full replacements with PUT