rest-api-design-patterns_skill

Overview

This skill is a comprehensive guide for designing, implementing, and maintaining RESTful APIs. It covers resource modeling, HTTP method semantics, versioning strategies, pagination, filtering, HATEOAS, error handling, and practical examples for modern frameworks like FastAPI and Express.js. The goal is to help teams build consistent, scalable, and maintainable HTTP APIs.

How this skill works

The skill inspects API design decisions and recommends concrete patterns: collection vs item resources, nested endpoints, query-based filtering, bulk operations, and actions that fall outside CRUD. It explains correct use of HTTP verbs (GET, POST, PUT, PATCH, DELETE), status codes, headers like Location, and caching semantics. It also presents versioning options (URI-based routers), pagination and sorting patterns, hypermedia links (HATEOAS), and examples of implementation and error handling for FastAPI and Express.js.

When to use it

• Designing a new REST API from scratch
• Refactoring or standardizing existing endpoints and semantics
• Building microservices that expose HTTP/REST interfaces
• Adding pagination, filtering, sorting, or bulk operations
• Introducing versioning or evolving public APIs
• Implementing consistent error handling and security patterns

Best practices

• Model resources as nouns and use plural collection names (e.g., /users, /orders)
• Limit nesting to 2–3 levels; expose child resources directly when needed
• Use appropriate HTTP verbs and semantics: PUT for replace, PATCH for partial updates, POST for create/actions
• Return proper status codes and headers (201 + Location on create, 204 for no-content deletes)
• Offer pagination, filtering, and sorting via query parameters and document defaults
• Version explicitly (URI versioning) and keep API changes backward compatible when possible

Example use cases

• Designing a product catalog API with search, category filters, and pagination
• Creating a microservice that exposes user and authorization endpoints following HTTP semantics
• Refactoring an endpoint set to replace RPC-like paths with resource-based URIs
• Implementing bulk create/update/delete endpoints for admin tooling
• Adding API versioning with separate routers and enhanced responses in v2