ClaudeBackend

REST API Designer — OpenAPI 3.0 Spec

Design RESTful APIs with proper resource modeling, status codes, auth strategy, and complete OpenAPI 3.0 documentation.

@promptallFeb 25, 2026 3892

You are a senior API architect. Design a complete REST API for:

**Product:** [DESCRIBE THE SYSTEM]
**Core resources:** [LIST 3-5 main entities]
**Auth method:** [JWT / OAuth2 / API Key]
**Scale:** [STARTUP MVP / GROWTH / ENTERPRISE]

Deliver:

### 1. Resource Modeling
- Entity relationship diagram (text format)
- URL structure following REST conventions

### 2. Endpoint Design
For each resource:
```
GET    /resources         — list with pagination
POST   /resources         — create
GET    /resources/:id     — get one
PATCH  /resources/:id     — partial update
DELETE /resources/:id     — soft delete
```

### 3. Request/Response Schemas
```json
// Request body and response envelope format
```

### 4. Error Handling Standards
- Status code usage (200/201/400/401/403/404/409/422/429/500)
- Error response format

### 5. Authentication & Authorization
- Token structure and expiry
- Role-based access rules per endpoint

### 6. OpenAPI 3.0 Snippet
YAML for 2-3 key endpoints

### 7. Rate Limiting Strategy
Limits per tier, headers to return

Result Text

## API Design — Multi-tenant SaaS Platform ### URL Structure ``` /api/v1/ workspaces/ # top-level tenant workspaces/:id/projects # nested resources projects/:id/tasks users/me # current user shortcut ``` ### Endpoint: Create Task ```yaml # OpenAPI 3.0 /projects/{projectId}/tasks: post: summary: Create a task security: [{ BearerAuth: [] }] requestBody: required: true content: application/json: schema: type: object required: [title] properties: title: { type: string, maxLength: 255 } assigneeId: { type: string, format: uuid } dueDate: { type: string, format: date } responses: '201': { description: Task created } '422': { description: Validation error } ``` ### Error Format (all errors) ```json { "error": { "code": "VALIDATION_FAILED", "message": "...", "fields": { "title": "required" } } } ```