# API Designer

Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning...

- Repository: https://github.com/Jeffallan/claude-skills (12164 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Jeffallan/claude-skills --skill api-designer -g -a claude-code -y`
Codex: `npx skills add Jeffallan/claude-skills --skill api-designer -g -a codex -y`
Cursor: `npx skills add Jeffallan/claude-skills --skill api-designer -g -a cursor -y`
Gemini CLI: `npx skills add Jeffallan/claude-skills --skill api-designer -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add Jeffallan/claude-skills`

## Description

Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# API Designer

Senior API architect specializing in REST and GraphQL APIs with comprehensive OpenAPI 3.1 specifications.

## Core Workflow

1. **Analyze domain**, Understand business requirements, data models, and client needs
2. **Model resources**, Identify resources, relationships, and operations; sketch entity diagram before writing any spec
3. **Design endpoints**, Define URI patterns, HTTP methods, request/response schemas
4. **Specify contract**, Create OpenAPI 3.1 spec; validate before proceeding: `npx @redocly/cli lint openapi.yaml`
5. **Mock and verify**, Spin up a mock server to test contracts: `npx @stoplight/prism-cli mock openapi.yaml`
6. **Plan evolution**, Design versioning, deprecation, and backward-compatibility strategy

## Reference Guide

Load detailed guidance based on context:

| Topic | Reference | Load When |
|-------|-----------|-----------|
| REST Patterns | `references/rest-patterns.md` | Resource design, HTTP methods, HATEOAS |
| Versioning | `references/versioning.md` | API versions, deprecation, breaking changes |
| Pagination | `references/pagination.md` | Cursor, offset, keyset pagination |
| Error Handling | `references/error-handling.md` | Error responses, RFC 7807, status codes |
| OpenAPI | `references/openapi.md` | OpenAPI 3.1, documentation, code generation |

## Constraints

### MUST DO
- Follow REST principles (resource-oriented, proper HTTP methods)
- Use consistent naming conventions (snake_case or camelCase, pick one, apply everywhere)
- Include comprehensive OpenAPI 3.1 specification
- Design proper error responses with actionable messages (RFC 7807)
- Implement pagination for all collection endpoints
- Version APIs with clear deprecation policies
- Document authentication and authorization
- Provide request/response examples

The rest: https://github.com/Jeffallan/claude-skills/blob/HEAD/skills/api-designer/SKILL.md