---
name: Designing APIs
slug: designing-apis
category: DevOps
description: Designing APIs guides the creation of REST and GraphQL APIs, covering endpoint structure, response formats, error handling, versioning, authentication, rate limiting, and OpenAPI documentation. Use it when creating new APIs, reviewing API contracts, or implementing REST or GraphQL patterns.
github: "https://github.com/CloudAI-X/claude-workflow-v2/tree/main/skills/designing-apis"
language: Python
stars: 1405
forks: 187
install: "npx degit https://github.com/CloudAI-X/claude-workflow-v2/tree/main/skills/designing-apis ~/.claude/skills/designing-apis"
installs_to: ~/.claude/skills/designing-apis
source_path: skills/designing-apis/SKILL.md
collection_size: 14
category_size: 798
collection_url: "https://dirskills.com/collections/CloudAI-X/claude-workflow-v2"
added: 2026-08-19T07:27:33.594Z
last_synced: 2026-08-19T07:27:33.594Z
canonical_url: "https://dirskills.com/skills/designing-apis"
---

# Designing APIs

Designing APIs guides the creation of REST and GraphQL APIs, covering endpoint structure, response formats, error handling, versioning, authentication, rate limiting, and OpenAPI documentation. Use it when creating new APIs, reviewing API contracts, or implementing REST or GraphQL patterns.

**Install:**

```bash
npx degit https://github.com/CloudAI-X/claude-workflow-v2/tree/main/skills/designing-apis ~/.claude/skills/designing-apis
```

## README

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

```json
{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  },
  "meta": {
    "requestId": "abc-123"
  }
}
```

**List Response with Pagination:**

```json
{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "last": "/users?page=5"
  }
}
```

**Error Response:**

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  },
  "meta": {
    "requestId": "abc-123"
  }
}
```

## API Versioning

**URL Versioning (Recommended):**

```
/api/v1/users
/api/v2/users
```

**Header Versioning:**

```
Accept: application/vnd.api+json; version=1
```

## Authentication Patterns

**JWT Bearer Token:**

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

**API Key:**

```
X-API-Key: your-api-key
```

## Rate Limiting Headers

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200
Retry-After: 60
```

## GraphQL Patterns

**Schema Design:**

```graphql
type Query {
  user(id: ID!): User
  users(filter: UserFilter, pagination: Pagination): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): UserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UserPayload!
}

type User {
  id: ID!
  name: String!
  email: String!
  orders(first: Int, after: String): OrderConnection!
}

input CreateUserInput {
  name: String!
  email: String!
}

type UserPayload {
  user: User
  errors: [Error!]
}
```

## OpenAPI Specification Template

See [OPENAPI-TEMPLATE.md](OPENAPI-TEMPLATE.md) for the full OpenAPI 3.0 specification template.

## API Design Validation

After completing the design, validate against this checklist:

```
Validation Checklist:
- [ ] All endpoints use nouns, not verbs
- [ ] HTTP methods match operations correctly
- [ ] Consistent response format across endpoints
- [ ] Error responses include actionable details
- [ ] Pagination implemented for list endpoints
- [ ] Authentication defined for protected endpoints
- [ ] Rate limiting headers documented
- [ ] OpenAPI spec is complete and valid
```

If validation fails, return to the relevant design step and address the issues.

## Security Checklist

- [ ] HTTPS only
- [ ] Authentication on all endpoints
- [ ] Authorization checks
- [ ] Input validation
- [ ] Rate limiting
- [ ] Request size limits
- [ ] CORS properly configured
- [ ] No sensitive data in URLs
- [ ] Audit logging