designing-apis_skill

Overview

This skill designs REST and GraphQL APIs with clear endpoint structures, error handling, versioning, authentication, and documentation. It provides practical patterns, response schemas, and validation checklists to produce consistent, secure, and maintainable API contracts.

How this skill works

I inspect resource models and relationships, then produce RESTful URLs or GraphQL schemas and recommended request/response formats. I specify HTTP status codes, standard error payloads, versioning strategy, authentication patterns, rate limit headers, and an OpenAPI-ready spec template. I also run the design through a validation checklist and a security checklist to catch common issues.

When to use it

• Creating a new REST or GraphQL API from domain models
• Designing or reviewing endpoint structure and naming
• Defining consistent request/response and pagination formats
• Specifying error handling, status codes, and rate limiting
• Preparing an OpenAPI spec or GraphQL schema for documentation

Best practices

• Use resource-based (noun) URLs for REST and operations mapped to proper HTTP methods
• Return consistent response envelopes with data, meta, and links for lists
• Provide structured error objects with codes, messages, and field-level details
• Version APIs explicitly (URL versioning recommended) and document changes
• Apply authentication, authorization, input validation, HTTPS, and rate limiting
• Document everything with OpenAPI for REST or a clear schema and payload types for GraphQL

Example use cases

• Designing /users and nested /users/:id/orders endpoints with pagination and filtering
• Drafting an OpenAPI 3.0 spec including success, list, and error response examples
• Converting CRUD endpoints to support PATCH/PUT semantics and proper status codes
• Creating a GraphQL schema with Query and Mutation types and payload error handling
• Defining JWT or API key authentication and rate limit headers in responses