playbooks

home / skills / tlabs-xyz / tbtc-v2-performance / backend-api

backend-api skill

/.claude/skills/backend-api

This skill helps you design and implement consistent RESTful APIs across frameworks, enforcing naming, versioning, authentication, and documentation.

npx playbooks add skill tlabs-xyz/tbtc-v2-performance --skill backend-api

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.8 KB
---
name: Backend API
description: Design and implement backend APIs following RESTful principles, consistent naming conventions, and API best practices. Use this skill when working on any backend API code including endpoints, routes, controllers, request handlers, response formatters, authentication mechanisms, API middleware, versioning strategies, or API documentation. Use when creating new API features, refactoring existing API code, implementing REST resources, designing API architecture, setting up API configuration, or working with any files in API-related directories (routes/, controllers/, api/, handlers/, middleware/). Use when working with Express.js, NestJS, FastAPI, Django REST Framework, Rails API, Spring Boot REST, or any other backend API framework.
---

## When to use this skill

- When creating or modifying API endpoints, routes, or controllers
- When implementing REST resource handlers
- When working with API middleware, guards, or interceptors
- When designing API architecture or structure
- When implementing API versioning strategies
- When working with request/response handling logic
- When creating or updating API authentication or authorization
- When implementing rate limiting or throttling
- When working with API configuration files
- When creating or updating API documentation
- When refactoring API code for consistency
- When working in API-related directories (routes/, controllers/, api/, handlers/, middleware/)
- When working with Express.js, NestJS, FastAPI, Django REST Framework, Rails API, Spring Boot REST, or similar frameworks

# Backend API

This Skill provides Claude Code with specific guidance on how to adhere to coding standards as they relate to how it should handle backend API.

## Instructions

For details, refer to the information provided in this file:
[backend API](../../../agent-os/standards/backend/api.md)

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

FAQ

What response format should I use?

Use a consistent JSON envelope containing data, metadata (optional), and an errors object. Return appropriate HTTP status codes and include machine-readable error codes for clients.

How should I handle validation?

Validate inputs at the boundary (request layer or middleware). Return 4xx errors with details about invalid fields and keep validation logic reusable.

When to version an API?

Version when making breaking changes to request/response shapes or authentication. Prefer starting with a clear versioning strategy (URI or header) before public release.