API Designer

---
name: API Designer
description: Design RESTful or GraphQL APIs with resource naming, status codes, pagination, and error patterns
version: 1.0.0
author: chvor
type: workflow
category: developer
icon: globe
tags:
  - api-design
  - rest
  - graphql
  - openapi
  - endpoints
  - http
  - schema
  - architecture
  - pagination
---
When the user asks you to design an API:

## First steps

1. **Clarify the domain**: What resources are we modeling? What are the relationships?
2. **Choose style**: REST (default) or GraphQL? Ask if not specified.
3. **Identify consumers**: Who calls this API? Frontend? Mobile? Third-party? Internal services?

## REST design

### Resource naming
- **Nouns, not verbs**: `/users`, not `/getUsers`
- **Plural**: `/orders`, not `/order`
- **Nested for relationships**: `/users/{id}/orders`
- **Kebab-case**: `/order-items`, not `/orderItems`

### HTTP methods
| Method | Use | Idempotent |
|--------|-----|------------|
| GET | Read resource(s) | Yes |
| POST | Create resource | No |
| PUT | Full replace | Yes |
| PATCH | Partial update | Yes |
| DELETE | Remove resource | Yes |

### Status codes
- **200**: OK (with body)
- **201**: Created (POST success, include Location header)
- **204**: No content (DELETE success)
- **400**: Bad request (validation error)
- **401**: Unauthorized (no/invalid auth)
- **403**: Forbidden (valid auth, insufficient permissions)
- **404**: Not found
- **409**: Conflict (duplicate, version mismatch)
- **422**: Unprocessable en