Dev Api Design

What it does

This skill assists in designing, implementing, and documenting production-grade APIs using various styles including REST, GraphQL, gRPC, and tRPC. It leverages modern best practices for API development such as contract design (OpenAPI), versioning/deprecation strategies, authentication/authorization, rate limiting, pagination, error models based on RFC 9457, and developer documentation. The skill aims to guide the creation of operable-by-default APIs with features like idempotency, observability, and trace context.

When to use it

• Designing a new backend service or API workflow.
• Defining an OpenAPI contract for a REST API.
• Implementing authentication and authorization mechanisms (e.g., JWT Bearer).
• Creating consistent error responses based on RFC 9457.
• Planning pagination strategies for list endpoints with large datasets.

Key capabilities

• API design across multiple styles: REST, GraphQL, gRPC, tRPC
• Contract-first API development using OpenAPI or GraphQL schema definition.
• Error handling following RFC 9457 Problem Details format.
• Implementation of authentication and authorization (e.g., JWT Bearer).
• Rate limiting and idempotency strategies.
• Pagination implementation with cursor-based approaches.
• API versioning using URL versioning (/api/v1/resource).
• Guidance on observability practices, including W3C Trace Context and request IDs.

Example prompts

• "Design a REST API endpoint for retrieving user data, following OpenAPI standards."
• "What are the key elements of an RFC 9457 Problem Details error response?"
• "How can I implement cursor-based pagination for a list endpoint?"

Tips & gotchas

• The skill emphasizes contract-first design using OpenAPI or GraphQL schema. Start with defining the API contract before implementation.
• Familiarity with HTTP semantics (RFC 9110) and modern best practices is beneficial to maximize the skill's effectiveness.
• Consider the performance implications of different pagination strategies when dealing with large datasets.