rest-api
Provides REST API design and implementation standards. Ensures proper URL structure, pagination, sorting, filtering, and error handling patterns. Specializes in RESTful principles, HTTP method semantics, status code usage, versioning strategies, HATEOAS, and API documentation. Implements consistent response structures and content negotiation.Use when: designing REST API endpoints, defining URL structures and naming conventions, implementing pagination/sorting/filtering, choosing appropriate HTTP methods (GET/POST/PUT/PATCH/DELETE), selecting HTTP status codes, designing request/response schemas, handling API errors and validation, implementing API versioning, documenting APIs with OpenAPI/Swagger, or designing hypermedia controls (HATEOAS).
When & Why to Use This Skill
This Claude skill provides comprehensive REST API design and implementation standards, ensuring high-quality URL structures, pagination, and error handling. It specializes in RESTful principles, HTTP semantics, and OpenAPI documentation to streamline backend development, improve API consistency, and enhance developer experience.
Use Cases
- Designing new RESTful endpoints with standardized URL naming conventions and resource nesting to ensure a logical API hierarchy.
- Implementing robust pagination and sorting mechanisms using industry-standard cursor-based patterns for high-performance data retrieval.
- Standardizing error responses using RFC 7807 (ProblemDetail) to provide clear, actionable feedback for client-side debugging.
- Defining consistent request/response schemas and versioning strategies to maintain backward compatibility during API evolution.
- Generating OpenAPI/Swagger documentation to ensure clear communication between backend and frontend teams.
| name | rest-api |
|---|---|
| description | | |
| Use when | designing REST API endpoints, defining URL structures and naming conventions, implementing pagination/sorting/filtering, choosing appropriate HTTP methods (GET/POST/PUT/PATCH/DELETE), selecting HTTP status codes, designing request/response schemas, handling API errors and validation, implementing API versioning, documenting APIs with OpenAPI/Swagger, or designing hypermedia controls (HATEOAS). |
REST API Design Standards
Naming Conventions
Field Naming
- Boolean: Require
is/has/canprefix - Date: Require
~Atsuffix - Use consistent terminology throughout the project (unify on either "create" or "add")
Date Format
- ISO 8601 UTC
- Use DateTime type
Pagination
Cursor-Based (Industry Standard)
- Parameters:
?cursor=xyz&limit=20 - Response:
{ data: [...], nextCursor: "abc", hasNext: true }
Sorting
?sortBy=createdAt&sortOrder=desc- Support multiple sort
- Specify defaults
Filtering
- Range:
{ min, max }or{ gte, lte } - Complex conditions use nested objects
URL Structure
Nested Resources
- Maximum 2 levels
Actions
- Allow verbs only when unable to represent as resource
/users/:id/activate
Response
List
data+ pagination info
Creation
- 201 + resource (excluding sensitive information)
Error (RFC 7807 ProblemDetail)
- Required:
type,title,status,detail,instance - Optional:
errorsarray
Batch
/batchsuffix- Success/failure count + results