Open Skills Logo
Open Skills

api-patterns

API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.

Author

@sickn33

Category

Development Tools

Install

Hot:7

Download and extract to your skills directory

Copy command and send to OpenClaw for auto-install:

Download and install this skill https://openskills.cc/api/download?slug=sickn33-skills-api-patterns&locale=en&source=copy

API Patterns - API Design Decision Assistant

API Patterns is an API design principles and decision-guidance skill that helps developers choose the appropriate API style (REST, GraphQL, tRPC) based on real-world scenarios, and guides response format design, versioning strategies, pagination implementation, and other key architectural decisions.

Applicable Scenarios

  • API architecture selection for new projects: When you start a new project and need to decide between REST, GraphQL, or tRPC, this skill provides decision trees and comparative analyses to help you choose based on the team’s technology stack, client requirements, and data complexity.

  • API refactoring and migration: When an existing API faces performance bottlenecks, over-fetching, or type-safety issues and you need to evaluate alternatives like GraphQL or tRPC, this skill provides migration paths and cautions.

  • API specification drafting and review: When a team needs to establish unified API design standards (resource naming, HTTP method usage, status code conventions, error handling), or review existing API designs for best-practice compliance, this skill offers checklists and anti-pattern warnings.

    • Core Features

  • API style decision support: Provides detailed comparisons of REST vs GraphQL vs tRPC, including each style’s strengths, limitations, and suitable scenarios. For example: REST is suitable for public APIs and simple CRUD; GraphQL fits complex data requirements and mobile clients; tRPC is ideal for TypeScript full-stack projects, offering end-to-end type safety.

  • API design standards guidance: Covers RESTful resource naming conventions, correct use of HTTP methods, status code selection, pagination strategies (cursor pagination vs offset pagination), error response format design, etc., ensuring consistency and maintainability.

  • API lifecycle management: Includes versioning strategies (URI versioning, Header versioning, Query parameter versioning), authentication scheme choices (JWT, OAuth, Passkey, API Keys), rate limiting protections (token bucket, sliding window), and documentation practices (OpenAPI/Swagger).

    • Frequently Asked Questions

    How to choose between REST, GraphQL, and tRPC?

    The choice depends on project context: REST is the most general and standardized option, suitable for public APIs and simple CRUD operations; GraphQL is suitable when clients need flexible queries, fewer network requests, and the data relationships are complex; tRPC is best for TypeScript full-stack projects, offering end-to-end type safety and a zero-configuration developer experience. The key questions to ask are: Who are the API consumers? What is the team’s tech stack? How complex are the data queries?

    What are best practices for API versioning?

    Common approaches include URI versioning (/v1/users), HTTP Header versioning (Accept: application/vnd.api.v1+json), and Query parameter versioning (?version=1). URI versioning is the most straightforward and suits public APIs; Header versioning keeps URLs cleaner but requires client cooperation; Query parameter versioning is the simplest but not recommended for complex scenarios. Regardless of the approach, plan deprecation policies and migration paths in advance.

    How to design a consistent API error response format?

    It is recommended to use an envelope pattern that wraps responses in a consistent structure: { data: {...}, errors: [...], meta: {...} }. Error details should include machine-readable error codes and human-readable messages, for example { "code": "VALIDATION_ERROR", "message": "Invalid email format", "field": "email" }. Avoid exposing internal stacks or database errors directly, and use appropriate HTTP status codes (4xx for client errors, 5xx for server errors).