api-designer

---
name: api-designer
description: API architecture design and documentation for RESTful, GraphQL, and gRPC services. Creates OpenAPI specifications, defines versioning strategies, and establishes authentication/authorization patterns. Use when user asks to design API, create endpoints, document REST/GraphQL, or plan API architecture.
license: MIT
---

# API Designer

Design high-quality API interfaces and output standardized interface documentation and design specifications.

## Core Capabilities

- RESTful/GraphQL/gRPC architecture design
- Unified naming conventions and error handling
- OpenAPI/Swagger documentation generation
- API versioning and backward compatibility
- Authentication, authorization, and rate limiting strategies

## Quick Reference

### HTTP Method Semantics

| Method | Purpose         | Idempotent |
|--------|-----------------|------------|
| GET    | Read resource   | ✅          |
| POST   | Create resource | ❌          |
| PUT    | Full update     | ✅          |
| PATCH  | Partial update  | ❌          |
| DELETE | Delete resource | ✅          |

### Common Status Codes

- `200` Success / `201` Created / `204` No Content
- `400` Bad Request / `401` Unauthorized / `403` Forbidden / `404` Not Found
- `500` Server Error

## Design Principles

1. **Resource-Oriented**: Use plural nouns in URLs, express actions with HTTP methods
2. **Unified Format**: Consistent request/response format, structured error messages
3. **Version Management**: URL or Header version control, backward compatibility
4. **Security First**: Authentication, authorization, input validation, rate limiting

## Boundaries

Focus on API design and documentation standards, not specific business logic implementation.

## When NOT to Use

- Writing implementation code → use `developer`
- Database schema design → use `database-engineer`
- Frontend UI development → use `frontend-design`
- Infrastructure or DevOps setup → use `devops-engineer`

## When To Use

Use this skill when the user asks to:

- design a new API or endpoint structure
- document existing APIs with OpenAPI/Swagger
- plan API versioning or migration strategy
- establish authentication/authorization patterns for APIs

## Quick Reference

**Always run `--help` first** to see usage.

- `scripts/openapi-gen.sh` - Generate OpenAPI documentation

## Detailed References

- `./workflows/api-design.md` - API design workflow
- `./guides/rest-api.md` - REST API design guide
- `./guides/graphql.md` - GraphQL API design guide
- `./guides/grpc.md` - gRPC API design guide

## Escalation Rules

Pause and ask the owner before:

- locking in an API style, auth model, or versioning strategy that has broad product impact
- expanding from interface design into implementation details outside this skill's boundary
- making compatibility assumptions that could break existing clients

## Final Output Contract (MANDATORY)

Every use of this skill should end with:

1. `Skill Fit` - why API design work was needed
2. `Primary Deliverable` - interface design, spec, or contract summary
3. `Execution Evidence` - references used, files produced, and validation performed
4. `Risks / Open Questions` - compatibility, auth, or rollout concerns
5. `Next Action` - the concrete documentation, review, or implementation step