# Designing Apis

Designs REST and GraphQL APIs including endpoints, error handling, versioning, and...

- Repository: https://github.com/CloudAI-X/claude-workflow-v2 (1421 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-06
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add CloudAI-X/claude-workflow-v2 --skill designing-apis -g -a claude-code -y`
Codex: `npx skills add CloudAI-X/claude-workflow-v2 --skill designing-apis -g -a codex -y`
Cursor: `npx skills add CloudAI-X/claude-workflow-v2 --skill designing-apis -g -a cursor -y`
Gemini CLI: `npx skills add CloudAI-X/claude-workflow-v2 --skill designing-apis -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add CloudAI-X/claude-workflow-v2`

## Description

Designs REST and GraphQL APIs including endpoints, error handling, versioning, and documentation. Use when creating new APIs, designing endpoints, reviewing API contracts, or when asked about REST, GraphQL, or API patterns.

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

# Designing APIs

### When to Load

- **Trigger**: Designing REST or GraphQL endpoints, API contracts, versioning, request/response formats
- **Skip**: Internal-only code with no API surface

## API Design Workflow

Copy this checklist and track progress:

```
API Design Progress:
- [ ] Step 1: Define resources and relationships
- [ ] Step 2: Design endpoint structure
- [ ] Step 3: Define request/response formats
- [ ] Step 4: Plan error handling
- [ ] Step 5: Add authentication/authorization
- [ ] Step 6: Document with OpenAPI spec
- [ ] Step 7: Validate design against checklist
```

## REST API Design

### URL Structure

```
# Resource-based URLs (nouns, not verbs)
GET    /users              # List users
GET    /users/:id          # Get user
POST   /users              # Create user
PUT    /users/:id          # Replace user
PATCH  /users/:id          # Update user
DELETE /users/:id          # Delete user

# Nested resources
GET    /users/:id/orders   # User's orders
POST   /users/:id/orders   # Create order for user

# Query parameters for filtering/pagination
GET    /users?role=admin&status=active
GET    /users?page=2&limit=20&sort=-createdAt
```

### HTTP Status Codes

| Code | Meaning           | Use Case                   |
| ---- | ----------------- | -------------------------- |
| 200  | OK                | Successful GET, PUT, PATCH |
| 201  | Created           | Successful POST            |
| 204  | No Content        | Successful DELETE          |
| 400  | Bad Request       | Invalid input              |
| 401  | Unauthorized      | Missing/invalid auth       |
| 403  | Forbidden         | Valid auth, no permission  |
| 404  | Not Found         | Resource doesn't exist     |
| 409  | Conflict          | Duplicate, state conflict  |
| 422  | Unprocessable     | Validation failed          |
| 429  | Too Many Requests | Rate limited               |
| 500  | Internal Error    | Server error               |

### Response Formats

**Success Response:**

The rest: https://github.com/CloudAI-X/claude-workflow-v2/blob/HEAD/skills/designing-apis/SKILL.md