# Api Design

> REST API conventions covering URL structure, HTTP methods, status codes, pagination, filtering, error responses, and versioning. Use when designing or reviewing REST API endpoints, adding routes, or standardizing API error handling.

- **Type:** Skill
- **Install:** `agentstack add skill-sagargupta16-claude-code-recipes-api-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Sagargupta16](https://agentstack.voostack.com/s/sagargupta16)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Sagargupta16](https://github.com/Sagargupta16)
- **Source:** https://github.com/Sagargupta16/claude-code-recipes/tree/main/skills/api-design
- **Website:** https://sagargupta.online

## Install

```sh
agentstack add skill-sagargupta16-claude-code-recipes-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

> REST API conventions: URL structure, HTTP methods, status codes, pagination, filtering, error responses, and versioning.

## URL Structure

1. **Use nouns, not verbs** -- the HTTP method provides the verb
2. **Use plural resource names** -- `/users`, `/orders`, `/products`
3. **Use kebab-case for multi-word resources** -- `/order-items`, not `/orderItems`
4. **Nest resources to show relationships** -- max 2 levels deep
5. **Use query parameters for filtering, not path segments**

```
# Good
GET    /api/v1/users
GET    /api/v1/users/123
GET    /api/v1/users/123/orders
POST   /api/v1/users
PATCH  /api/v1/users/123
DELETE /api/v1/users/123

# Bad
GET    /api/v1/getUsers
GET    /api/v1/user/123
POST   /api/v1/users/123/orders/456/items/789/notes   # too deeply nested
```

## HTTP Methods

| Method | Purpose | Idempotent | Request Body | Success Code |
|--------|---------|:----------:|:------------:|:------------:|
| GET | Read resource(s) | Yes | No | 200 |
| POST | Create resource | No | Yes | 201 |
| PUT | Replace resource entirely | Yes | Yes | 200 |
| PATCH | Partial update | No* | Yes | 200 |
| DELETE | Remove resource | Yes | No | 204 |

*PATCH is not guaranteed idempotent, but should be designed to be when possible.

### Rules

1. **GET requests must be safe** -- no side effects, no state changes
2. **POST for creation** -- return the created resource with `Location` header
3. **Use PATCH over PUT** -- partial updates are more practical than full replacement
4. **DELETE should be idempotent** -- deleting a non-existent resource returns 204, not 404

## Status Codes

Use the correct status code. When in doubt, refer to this table:

### Success (2xx)

| Code | Meaning | When to Use |
|------|---------|-------------|
| 200 | OK | Successful GET, PUT, PATCH |
| 201 | Created | Successful POST that creates a resource |
| 204 | No Content | Successful DELETE, or PUT/PATCH with no response body |

### Client Errors (4xx)

| Code | Meaning | When to Use |
|------|---------|-------------|
| 400 | Bad Request | Malformed JSON, invalid field values, validation errors |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Authenticated but lacks permission |
| 404 | Not Found | Resource does not exist |
| 409 | Conflict | Duplicate resource, state conflict |
| 422 | Unprocessable Entity | Valid JSON but fails business rules |
| 429 | Too Many Requests | Rate limit exceeded |

### Server Errors (5xx)

| Code | Meaning | When to Use |
|------|---------|-------------|
| 500 | Internal Server Error | Unexpected server failure |
| 502 | Bad Gateway | Upstream service failure |
| 503 | Service Unavailable | Server overloaded or in maintenance |

## Error Responses

Use a consistent error format across all endpoints:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address.",
        "code": "INVALID_FORMAT"
      },
      {
        "field": "age",
        "message": "Must be at least 18.",
        "code": "MIN_VALUE"
      }
    ]
  }
}
```

### Rules

1. **Always include a machine-readable error code** -- `VALIDATION_ERROR`, `NOT_FOUND`, `RATE_LIMITED`
2. **Include a human-readable message** -- suitable for developer debugging
3. **Never expose internal errors** -- no stack traces, SQL queries, or file paths in production
4. **Field-level errors in `details` array** -- for validation errors, specify which field failed

## Pagination

Use cursor-based pagination for large datasets, offset-based for simple cases.

### Offset-based (simple)

```
GET /api/v1/users?page=2&per_page=25

Response:
{
  "data": [ ... ],
  "pagination": {
    "page": 2,
    "per_page": 25,
    "total": 150,
    "total_pages": 6
  }
}
```

### Cursor-based (scalable)

```
GET /api/v1/users?limit=25&cursor=eyJpZCI6MTAwfQ

Response:
{
  "data": [ ... ],
  "pagination": {
    "limit": 25,
    "has_more": true,
    "next_cursor": "eyJpZCI6MTI1fQ"
  }
}
```

### Rules

1. **Default page size: 25, max: 100** -- prevent clients from requesting unlimited data
2. **Always return pagination metadata** -- clients need to know if there are more pages
3. **Use cursor-based for real-time data or large tables** -- offset-based breaks with concurrent writes

## Filtering and Sorting

```
# Filter by field values
GET /api/v1/users?status=active&role=admin

# Date ranges
GET /api/v1/orders?created_after=2025-01-01&created_before=2025-12-31

# Search
GET /api/v1/products?q=keyboard

# Sort (prefix with - for descending)
GET /api/v1/users?sort=created_at
GET /api/v1/users?sort=-updated_at

# Combine everything
GET /api/v1/orders?status=shipped&sort=-created_at&page=1&per_page=25
```

### Rules

1. **Use `snake_case` for query parameter names**
2. **Support multiple sort fields** -- `?sort=-created_at,name`
3. **Validate all filter parameters** -- return 400 for unknown fields
4. **Document allowed filter fields per endpoint**

## Request and Response Conventions

1. **Use `snake_case` for all JSON keys** -- `created_at`, `first_name`, `order_id`
2. **Use ISO 8601 for dates** -- `2025-06-15T14:30:00Z`
3. **Use UUIDs or opaque strings for IDs** -- avoid exposing auto-increment integers
4. **Wrap collections in a `data` key** -- `{ "data": [...] }`, not a bare array
5. **Include `created_at` and `updated_at` in all resources**
6. **Use `null` for absent optional fields** -- don't omit them entirely

```json
{
  "data": {
    "id": "usr_a1b2c3d4",
    "email": "user@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "role": "admin",
    "avatar_url": null,
    "created_at": "2025-06-15T14:30:00Z",
    "updated_at": "2025-06-15T14:30:00Z"
  }
}
```

## Versioning

1. **Use URL path versioning** -- `/api/v1/`, `/api/v2/`
2. **Increment the major version only for breaking changes**
3. **Support the previous version for at least 6 months after deprecation**
4. **Return a `Deprecation` header on deprecated endpoints**
5. **Document migration guides between versions**

## Authentication

1. **Use Bearer tokens in the `Authorization` header** -- `Authorization: Bearer `
2. **Never pass tokens in query parameters** -- they end up in server logs
3. **Return 401 for missing/invalid tokens, 403 for insufficient permissions**
4. **Include rate limit headers** -- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

## Anti-patterns

- **Verbs in URLs** -- use HTTP methods instead
- **Returning 200 with error body** -- use proper status codes
- **Nested resources deeper than 2 levels** -- flatten with query parameters
- **Inconsistent naming** -- pick `snake_case` or `camelCase` and stick with it
- **Missing pagination on list endpoints** -- always paginate collections
- **Exposing internal IDs** -- use prefixed opaque IDs like `usr_`, `ord_`, `prod_`

## Source & license

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

- **Author:** [Sagargupta16](https://github.com/Sagargupta16)
- **Source:** [Sagargupta16/claude-code-recipes](https://github.com/Sagargupta16/claude-code-recipes)
- **License:** MIT
- **Homepage:** https://sagargupta.online

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-sagargupta16-claude-code-recipes-api-design
- Seller: https://agentstack.voostack.com/s/sagargupta16
- 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%.