# API Design Patterns

REST API design with resource naming, pagination, versioning, and OpenAPI spec generation

- Repository: https://github.com/rohitg00/awesome-claude-code-toolkit (2800 stars)
- Category: Design
- License: Apache-2.0
- Last updated: 2026-05-12
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add rohitg00/awesome-claude-code-toolkit --skill api-design-patterns -g -a claude-code -y`
Codex: `npx skills add rohitg00/awesome-claude-code-toolkit --skill api-design-patterns -g -a codex -y`
Cursor: `npx skills add rohitg00/awesome-claude-code-toolkit --skill api-design-patterns -g -a cursor -y`
Gemini CLI: `npx skills add rohitg00/awesome-claude-code-toolkit --skill api-design-patterns -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add rohitg00/awesome-claude-code-toolkit`

## Description

REST API design with resource naming, pagination, versioning, and OpenAPI spec generation

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

# API Design Patterns

## Resource Naming

- Use plural nouns: `/users`, `/orders`, `/products`
- Nest for relationships: `/users/{id}/orders`
- Max nesting depth: 2 levels. Beyond that, use query params or top-level resources
- Use kebab-case: `/user-profiles`, not `/userProfiles`
- Never put verbs in URLs: `/users/{id}/activate` is wrong, use `POST /users/{id}/activation`

## HTTP Methods

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

Return `Location` header on POST with the URL of the created resource.

## Status Codes

```
200 OK              - Successful read/update
201 Created         - Successful creation
204 No Content      - Successful delete
400 Bad Request     - Validation error (include field-level errors)
401 Unauthorized    - Missing or invalid authentication
403 Forbidden       - Authenticated but not authorized
404 Not Found       - Resource does not exist
409 Conflict        - State conflict (duplicate, version mismatch)
422 Unprocessable   - Semantically invalid (valid JSON, bad values)
429 Too Many Reqs   - Rate limited (include Retry-After header)
500 Internal Error  - Unhandled server error (never expose stack traces)
```

## Error Response Format

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

Use consistent error codes across the API. Document every code in your API reference.

## Cursor-Based Pagination (preferred)

```
GET /users?limit=20&cursor=eyJpZCI6MTAwfQ

The rest: https://github.com/rohitg00/awesome-claude-code-toolkit/blob/HEAD/skills/api-design-patterns/SKILL.md