api-design-patterns

Files (4)

• SKILL.md
• error-codes.md · references/
• openapi-template.md · references/
• sdk-patterns.md · references/

SKILL.md (first lines)

# API Design Patterns

Build APIs that developers love to use.

## Design Principles

### The Three Laws of API Design

1. **Predictable**: Consistent patterns throughout
2. **Discoverable**: Self-documenting, intuitive naming
3. **Evolvable**: Can change without breaking clients

### API-First Mindset

```
Design → Document → Mock → Build → Test → Deploy

NOT: Build → Document (maybe) → Hope it works
```

---

## REST Patterns

### Resource Naming

```
# Collection
GET    /users              # List users
POST   /users              # Create user

# Item
GET    /users/{id}         # Get user
PUT    /users/{id}         # Replace user
PATCH  /users/{id}         # Update user
DELETE /users/{id}         # Delete user

# Nested resources
GET    /users/{id}/posts   # User's posts
POST   /users/{id}/posts   # Create post for user

# Actions (when CRUD doesn't fit)
POST   /users/{id}/activate
POST   /orders/{id}/cancel
```

### Naming Conventions

| Do | Don't |
|----|-------|
| `/users` | `/getUsers`, `/user-list` |
| `/users/{id}` | `/users/get/{id}` |
| `/users/{id}/posts` | `/getUserPosts` |
| Plural nouns | Verbs in URLs |
| Lowercase, hyphens | camelCase, underscores |

### HTTP Methods

| Method | Purpose | Idempotent | Safe |
|--------|---------|------------|------|
| GET | Read | Yes | Yes |
| POST | Create | No | No |
| PUT | Replace | Yes | No |
| PATCH | Update | No* | No |
| DELETE | Remove | Yes | No |

*PATCH can be idempotent if designed carefully

### Status Codes

| Code | Meaning | Use When |
|------|---------|----------|
| 200 | OK | Successful GET, PUT, PATCH |
| 201 | Created | Successful POST with new resource |
| 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 | Valid syntax, invalid semantics |
| 429 | Too Many Requests | Rate limited |
| 500 | Server Error | Unhandled server error |

---

## Request/Response Patterns

### Request Body

```json
{
  "email": "user@example.com",
  "name": "John Doe",
  "preferences": {
    "newsletter": true
  }
}
```

### Response: Single Resource

```json
{
  "data": {
    "id": "usr_123",
    "type": "user",
    "attributes": {
      "email": "user@example.com",
      "name": "John Doe",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    "relationships": {
      "organization": {
        "id": "org_456",
        "type": "organization"
      }
    }
  }

From 4444J99/a-i--skills, MIT.

More from 4444J99/a-i--skills