backend-api_skill

Overview

This skill helps design and implement backend APIs following RESTful principles, consistent naming, and API best practices. It guides creation and refactoring of endpoints, routes, controllers, middleware, authentication, and versioning. Use it to ensure predictable request/response behavior, clear error handling, and maintainable API structure.

How this skill works

The skill inspects API code and suggests concrete changes: consistent route naming, resourceful controllers, standardized response shapes, status codes, and error payloads. It reviews middleware, authentication flows, rate limiting, and versioning strategies and proposes improvements aligned with common frameworks (Express, NestJS, FastAPI, Django REST Framework, Rails, Spring Boot). It also provides snippets and configuration patterns tailored to TypeScript projects and common server frameworks.

When to use it

• Creating or modifying API endpoints, routes, or controllers
• Implementing REST resource handlers or response formatters
• Designing or refactoring API architecture and versioning strategies
• Implementing authentication, authorization, or rate limiting
• Working with API middleware, guards, or request/response logic

Best practices

• Follow resource-based, plural route naming (e.g., GET /users, POST /users) and use HTTP verbs consistently
• Return predictable response envelopes with proper status codes and a clear error schema
• Keep controllers thin: validate and parse input, delegate business logic to services, return normalized responses
• Use middleware for cross-cutting concerns (auth, validation, logging, rate limiting) and keep it composable
• Adopt explicit API versioning (URI or header) and maintain backward compatibility with deprecation notices
• Document endpoints with OpenAPI/Swagger and include example requests, responses, and error cases

Example use cases

• Add a new RESTful resource and its CRUD routes with consistent naming and validation
• Refactor inconsistent controllers to use shared service layer and standardized response format
• Implement JWT-based authentication middleware and role-based authorization checks
• Introduce API versioning and a migration plan to preserve existing clients
• Add rate limiting and structured error handling for high-traffic endpoints