api-design_skill

Overview

This skill provides pragmatic REST API design patterns, response formats, validation, and controller structure for building robust backend endpoints. It focuses on consistent responses, correct HTTP status codes, input validation, pagination, and error handling. Use it to implement CRUD endpoints, actions, and webhook handlers with predictable behavior.

How this skill works

The skill defines route organization, controller patterns, and response helpers to standardize API output (success, error, paginated, item). It recommends Yup schemas and validation middleware to sanitize input and return structured validation errors. Controllers follow a try/catch pattern, scope queries by tenant/shop, and use response helpers to set status and body consistently.

When to use it

• Creating new CRUD endpoints or controller actions
• Designing API response formats and error codes
• Adding input validation and sanitization
• Implementing pagination for list endpoints
• Standardizing status codes and error handling

Best practices

• Use response helpers (successResponse, errorResponse, paginatedResponse, itemResponse) for consistent output
• Validate all inputs with Yup and strip unknown fields before processing
• Return correct HTTP status codes (201 for create, 204 for delete, 400/422 for client errors, 500 for server errors)
• Scope queries by tenant/shopId and pick only public response fields
• Prefer cursor-based pagination for large data sets and include pagination meta

Example use cases

• Add POST /customers with createCustomerSchema validation and return 201 with itemResponse
• Implement GET /customers?limit=&cursor= using cursor pagination and paginatedResponse
• Protect routes with authentication middleware and return UNAUTHORIZED or FORBIDDEN error codes
• Handle resource lookup in controllers and return 404 with errorResponse when not found
• Add an action endpoint POST /customers/:id/points/award that validates payload and returns updated item