What does this skill do?

The REST API Design Skill provides a set of conventions and best practices for designing consistent, robust, and easy-to-use REST APIs. It addresses common issues related to resource naming, error handling, pagination, and versioning, ensuring that any new or existing API follows a predictable, developer-friendly contract.

Design of New Endpoints
Define resources, URLs, and HTTP methods when creating new backend services from scratch.
Review of Existing Contracts
Audit existing APIs to ensure consistency in naming conventions, errors, and responses.
Error Handling and Pagination
Implements standardized error formats and cursor-based pagination for large collections.
Versioning Strategy
Plan API versioning using /api/v1/ and manage breaking changes in a controlled manner.

Usage examples

🆕 Design from scratch
I need to design a REST API to manage orders for an online store. Define the endpoints, methods, and response formats.
🔍 Consistency Check
Take a look at these endpoints from my current API and let me know if they follow best practices for naming conventions and HTTP semantics.
📄 Error Format
Design a standardized error response format for my API, including codes, messages, and validation details.
🔄 Versioning Strategy
Help me plan the versioning of my public API. When should I move from v1 to v2?

Features

Resource Nomenclature Plural nouns, lowercase letters, and kebab-case for predictable, developer-friendly URLs.
Complete HTTP Semantics Correct use of GET, POST, PUT, PATCH, and DELETE based on the intent of each operation.
Standardized Responses An object wrapper containing data for successes and an error object containing codes and details for failures.
Pagination by Cursor Efficient pagination for large datasets with metadata and navigation links.
Versioning and Security Versioning strategy using /api/v1/ and authentication via Bearer tokens with resource-level authorization.

Frequently asked questions

No. This skill is a guide to patterns and conventions. It works directly with Claude Code or Cowork without any additional configuration.
The skill includes examples in TypeScript using Next.js API Routes and validation with Zod, but the conventions apply to any language or framework.
Yes. The conventions cover both internal and public APIs, as well as partner-facing APIs, including security using Bearer tokens.
Of course. The skill serves as a foundation for best practices; you can adjust the patterns based on your team's specific needs.
REST API Design — Consistent and Robust APIs with Claude AI

¿Prefieres escuchar el contenido? Genera la narración de audio con un clic.