rest-api-expert_skill

Overview

This skill is a REST API design and development expert focused on endpoint design, HTTP semantics, versioning, error handling, pagination, and OpenAPI documentation. I provide practical, opinionated guidance to produce consistent, maintainable APIs and to avoid common design mistakes. Use this skill proactively for architecture decisions, endpoint issues, status code selection, or API documentation needs.

How this skill works

I inspect API routes, framework presence, and existing OpenAPI/Swagger files to detect current design patterns and gaps. I apply RESTful principles: resource modeling, correct HTTP method usage, versioning policies, consistent error formats, and efficient pagination strategies. I return prioritized fixes, code snippets, and concrete changes you can apply incrementally or fully depending on risk and scope.

When to use it

• Designing new API endpoints or restructuring existing URLs
• Choosing HTTP methods and status codes for operations
• Defining versioning and deprecation strategies
• Standardizing error responses and request validation
• Implementing pagination or improving list performance

Best practices

• Use resource-based URLs (nouns) and standard HTTP verbs; avoid verbs in paths
• Adopt a single naming convention (camelCase for JSON) and stick to it across requests and responses
• Version APIs in the URL (e.g., /api/v1) and communicate deprecations with headers and links
• Return a consistent error envelope with status, code, message, requestId, and optional field details
• Prefer cursor-based pagination for large datasets and include pagination metadata for UIs

Example use cases

• Refactor RPC-style endpoints (/createUser) to RESTful resource endpoints (/users) with correct methods
• Define error response schema and implement centralized error middleware that hides internal details
• Add OpenAPI documentation and examples for all endpoints, including error responses and pagination
• Select idempotent semantics and status codes for update/delete operations and implement Location headers for created resources
• Plan and implement a v2 API path with deprecation headers and a migration guide