Can I use this for designing error handling?

Absolutely. It defines specific HTTP status codes for common scenarios like 400 for validation errors, 401 for authentication, and 429 for rate limiting.

Does it include support for pagination?

Yes, it provides standardized structures for collection responses that include metadata for page numbers, limits, total counts, and navigation links.

How does this skill help with API naming conventions?

The skill enforces a resource-oriented approach using plural nouns and hierarchical paths (e.g., /users/123/orders) instead of verb-based URLs, making your API more intuitive.

Is the output compatible with OpenAPI?

Yes, the design patterns and best practices provided by this skill align with OpenAPI/Swagger standards, facilitating easier documentation later.

Why does it distinguish between PUT and PATCH?

It provides guidance on using PUT for full resource replacement and PATCH for partial updates, ensuring your API correctly follows idempotency standards.

REST API Design

Name: REST API Design
Author: secondsky

bysecondsky

•

API Development

Architects production-ready RESTful APIs using industry-standard naming conventions, HTTP methods, and response formats.

This skill empowers Claude to design developer-friendly and consistent RESTful interfaces by enforcing best practices in resource-oriented architecture. It provides standardized patterns for hierarchical resource naming, correct HTTP method implementation (including idempotency rules), and precise status code mapping for both success and error states. By establishing uniform response structures for individual objects and paginated collections, it ensures that your backend services remain maintainable, scalable, and easy for frontend teams to consume.

Key Features

01Standardized JSON response formats for single resources and paginated collections

0221 GitHub stars

03Comprehensive HTTP status code guidance for success, validation, and authorization states

04Precise HTTP method mapping for GET, POST, PUT, PATCH, and DELETE operations

05Standardized plural noun-based resource naming and hierarchical URL structures

06Pre-defined patterns for query parameters including filtering, sorting, and field selection

Use Cases

01Architecting new backend services from scratch with consistent API conventions

02Refactoring existing endpoints to improve developer experience and standardization

03Establishing organizational API style guides and implementation patterns

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add secondsky/claude-skills rest-api-design

For use in Claude.ai and ChatGPT

Download Skill