designing-apis_skill

Overview

This skill helps design APIs that are secure, scalable, and maintainable using RESTful, GraphQL, and event-driven patterns. It focuses on resource modeling, versioning, error formats, pagination, rate limiting, and security design. Use it to choose the right API style and establish consistent standards across teams.

How this skill works

The skill guides selection between REST, GraphQL, WebSockets, and message queues based on requirements like public access, real-time needs, and data complexity. It provides concrete patterns for resource-oriented REST design, HTTP semantics, RFC 7807 error responses, pagination strategies (offset, cursor, keyset), rate limiting with token buckets, and OAuth2/key management. It also outlines OpenAPI and AsyncAPI structures and GraphQL schema best practices including N+1 mitigation.

When to use it

• Designing a new public or internal API (REST, GraphQL, or event-driven)
• Choosing the right protocol for realtime, complex data, or microservices
• Creating API standards, versioning policy, and deprecation timelines
• Defining error response formats, pagination, and rate limiting behavior
• Drafting OpenAPI or AsyncAPI specifications and API contract documentation

Best practices

• Model resources as nouns and limit nesting depth to 2–3 levels for REST
• Use URL path versioning for public APIs and provide deprecation headers and migration timelines
• Prefer RFC 7807 problem+json for structured error responses with field-level error details
• Choose cursor or keyset pagination for large or rapidly changing datasets; use offset for small simple collections
• Expose rate limit headers (Limit, Remaining, Reset) and apply tiered limits by user, key, or IP
• Define OAuth2 flows and scope-based authorization; store hashed API keys and support rotation

Example use cases

• Design a public CRUD API for a SaaS product using REST with OpenAPI for SDK generation
• Design a GraphQL schema for a client-facing dashboard needing flexible queries and batched resolvers
• Define an event-driven contract (AsyncAPI) for microservices communicating via Kafka or MQTT
• Create a versioning and deprecation policy for breaking API changes and rollout plan
• Specify pagination and rate limiting for a large user feed with cursor-based navigation