# Api Design

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-iwritec0de-app-dev-api-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [iwritec0de](https://agentstack.voostack.com/s/iwritec0de)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [iwritec0de](https://github.com/iwritec0de)
- **Source:** https://github.com/iwritec0de/app-dev/tree/main/skills/api-design

## Install

```sh
agentstack add skill-iwritec0de-app-dev-api-design
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# API Design Patterns

## REST Resource Design

### URL Structure
```
GET    /api/v1/resources          — List (with pagination)
GET    /api/v1/resources/:id      — Get single
POST   /api/v1/resources          — Create
PUT    /api/v1/resources/:id      — Full update
PATCH  /api/v1/resources/:id      — Partial update
DELETE /api/v1/resources/:id      — Delete

# Nested resources
GET    /api/v1/users/:id/posts    — User's posts
POST   /api/v1/users/:id/posts    — Create post for user

# Actions (non-CRUD)
POST   /api/v1/orders/:id/cancel  — Action on resource
POST   /api/v1/auth/login         — Authentication
POST   /api/v1/auth/refresh       — Token refresh
```

### Naming Rules
- Plural nouns for resources (`/users`, not `/user`)
- Kebab-case for multi-word (`/user-profiles`, not `/userProfiles`)
- No verbs in URLs (`/users`, not `/getUsers`)
- No trailing slashes

## HTTP Status Codes

| Code | When to Use |
|------|-------------|
| 200 | Successful GET, PUT, PATCH, or DELETE |
| 201 | Successful POST (resource created). Include `Location` header. |
| 204 | Successful DELETE with no response body |
| 400 | Invalid request (validation error, malformed JSON) |
| 401 | Not authenticated (missing or invalid credentials) |
| 403 | Authenticated but not authorized |
| 404 | Resource not found |
| 409 | Conflict (duplicate resource, version mismatch) |
| 422 | Semantically invalid (valid JSON, but business logic rejects it) |
| 429 | Rate limit exceeded. Include `Retry-After` header. |
| 500 | Server error (never expose internals) |

## Response Formats

### Success (Direct)
```json
{
  "id": "uuid",
  "name": "Example",
  "createdAt": "2025-01-01T00:00:00Z"
}
```

### Success (Envelope)
```json
{
  "data": { ... },
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 150
  }
}
```

### Error
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  }
}
```

## Pagination

### Cursor-Based (Recommended)
```
GET /api/users?cursor=abc123&limit=20

Response:
{
  "data": [...],
  "pagination": {
    "nextCursor": "def456",
    "hasMore": true
  }
}
```

### Offset-Based
```
GET /api/users?page=2&perPage=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 2,
    "perPage": 20,
    "total": 150,
    "totalPages": 8
  }
}
```

## Authentication Patterns

### JWT Bearer Token
```
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Access token: short-lived (15-60 min)
Refresh token: long-lived (7-30 days), stored securely
```

### API Key
```
X-API-Key: sk_live_abc123...

Use for: server-to-server, public data APIs
Never for: user-facing authentication
```

### OAuth 2.0 Flows
- **Authorization Code** — Web apps (most secure)
- **PKCE** — SPAs and mobile apps
- **Client Credentials** — Service-to-service
- **Device Code** — CLI tools and IoT

## Rate Limiting

Include headers in responses:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1672531200
Retry-After: 60
```

Common limits:
- Anonymous: 60 requests/minute
- Authenticated: 1000 requests/minute
- Auth endpoints (login): 10 requests/minute (brute-force prevention)

## Versioning

### URL Path (Recommended)
```
/api/v1/users
/api/v2/users
```

### Header
```
Accept: application/vnd.myapi.v2+json
```

### Query Parameter
```
/api/users?version=2
```

## Caching

```
# Immutable resources
Cache-Control: public, max-age=31536000, immutable

# Dynamic but cacheable
Cache-Control: public, max-age=60, stale-while-revalidate=30

# Never cache
Cache-Control: no-store

# ETag for conditional requests
ETag: "abc123"
If-None-Match: "abc123"  → 304 Not Modified
```

## Security Headers

```
Content-Type: application/json
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000
```

## Input Validation Rules

- Validate ALL input (body, query, params, headers)
- Whitelist allowed fields (don't pass raw input to DB)
- Set max lengths on strings
- Set min/max on numbers
- Validate email, URL, UUID formats
- Sanitize HTML in text fields
- Reject unknown fields (strict mode)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [iwritec0de](https://github.com/iwritec0de)
- **Source:** [iwritec0de/app-dev](https://github.com/iwritec0de/app-dev)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-iwritec0de-app-dev-api-design
- Seller: https://agentstack.voostack.com/s/iwritec0de
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.