domains / software-engineering / api-design / api-designer

api-designer

Skill card

combined

The two copies overlap in scope (REST API design) but prescribe different procedures and artifacts. Jeffallan/claude-skills is an architect workflow that mandates OpenAPI 3.1, resource modeling, linting with Redocly, mocking with Prism, and RFC 7807 error schemas. sickn33/agentic-awesome-skills is a generation skill that asks the user to choose between endpoints-only or detailed design, then outputs a fixed Markdown/JSON endpoint template with a page/limit pagination envelope and /api/v1/ versioning. They disagree on output format (OpenAPI spec vs Markdown endpoint tables), pagination (cursor vs page/limit), and versioning (strategy vs /api/v1/ prefix), so crowning one would hide a real alternative.

Repositories

Other copies

Combined skill

# API Designer

Use when designing REST APIs, creating endpoint specifications, or planning API architecture.

## 1. Clarify scope
- Ask the user whether they want endpoints only or a detailed design, unless the request already specifies the level of detail.
- Understand business requirements, data models, and client needs.

## 2. Model resources
- Identify resources, relationships, and operations.
- Sketch an entity diagram before writing any spec.
- Cover all major resources for the described system; infer resources if the user does not list them.
- Always include CRUD where applicable, plus domain-specific actions.

## 3. Design endpoints
- Use RESTful conventions: plural nouns for collections, nested paths for relationships (e.g. /hotels/{id}/rooms).
- Do not use verbs in resource URIs (use /users/{id}, not /getUser/{id}).
- Define URI patterns, HTTP methods, request/response schemas.
- Group endpoints by resource (e.g. Authentication, Hotels, Rooms, Bookings, Payments, Reviews).

## 4. Specify the contract
- Create an OpenAPI 3.1 specification.
- Validate before proceeding: npx @redocly/cli lint openapi.yaml
- Include comprehensive request/response examples.
- Document authentication and authorization.
- Design proper error responses with actionable messages (RFC 7807 problem+json).
- Implement pagination for all collection endpoints.
- Version APIs with a clear deprecation policy; default to /api/v1/ prefix unless the user specifies otherwise.

## 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.
- Do not create breaking changes without a migration path.

## Output format

For each endpoint group (resource), output:

### RESOURCE NAME

#### METHOD /path/to/endpoint
> Short description (max two lines).

**Headers**
| Header | Value | Required |
|--------|-------|----------|
| Content-Type | application/json | Yes |
| Authorization | Bearer <token> | Yes/No |

**Request Body** (omit for GET/DELETE if no body)
```json
{ "field": "type — description" }
```

**Success Response** — STATUS_CODE Description
```json
{ "field": "value or type" }
```

**Error Codes**
| Code | Meaning |
|------|---------|
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 409 | Conflict |
| 422 | Unprocessable Entity |
| 500 | Internal Server Error |

## Pagination

Use cursor-based pagination in the OpenAPI spec (next_cursor, has_more). For Markdown endpoint tables, include query params (page, limit, sort, filter) and wrap responses in a paginated envelope:

```json
{ "data": [...], "pagination": { "total": 100, "page": 1, "limit": 20, "totalPages": 5 } }
```

## Auth patterns

| Scenario | Auth Method |
|----------|-------------|
| User-facing apps | Authorization: Bearer <JWT> |
| Server-to-server | X-Api-Key: <key> |
| Public endpoints | No auth header |
| Admin endpoints | Bearer token + role check (403 if not admin) |

## 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

### MUST NOT DO
- Use verbs in resource URIs
- Return inconsistent response structures
- Skip error code documentation
- Ignore HTTP status code semantics
- Design APIs without a versioning strategy
- Expose implementation details in the API surface
- Create breaking changes without a migration path
- Omit rate limiting considerations

## After completing the design

Ask the user: "Would you like me to generate API documentation for this design? (yes/no)"
- If yes and an API Documentation skill is available, follow it using the design output as input.
- If the skill is not available, inform the user and offer basic documentation.