api-patterns_skill

Overview

This skill teaches practical API design principles and decision-making for modern services. It helps choose between REST, GraphQL, and tRPC, and covers response formats, versioning, pagination, and related operational concerns. The focus is on thinking through trade-offs and applying patterns appropriately rather than copy-pasting templates.

How this skill works

It guides you through a decision flow that matches API style to consumer needs, team constraints, and deployment patterns. It inspects common concerns—naming, HTTP semantics, type safety, response envelopes, error handling, and versioning—and gives concrete recommendations. It also highlights anti-patterns and a checklist to validate design choices before implementation.

When to use it

• Selecting an API style for a new product or microservice
• Refining response formats and error contracts for client teams
• Planning API versioning and migration strategies
• Choosing pagination and filtering approaches for large datasets
• Deciding auth, rate limiting, and security testing needs

Best practices

• Base style choice on client needs and team expertise, not inertia
• Use consistent response envelopes and clear error schemas across endpoints
• Prefer nouns and resource-based routes in REST; avoid verbs in URLs
• Adopt semantic HTTP status codes and standard pagination metadata
• Plan versioning up front (URI/header/query) and document migration paths
• Include rate limiting and basic security checks early in design

Example use cases

• Choosing GraphQL for rich client-driven querying and reduced round trips
• Picking tRPC in a TypeScript monorepo to leverage end-to-end typesafety
• Designing REST endpoints with clear resource names and correct HTTP methods
• Defining a stable versioning strategy for public APIs to support backward compatibility
• Implementing consistent error envelopes and pagination for mobile clients