API Documenter

openapi: 3.1.0
info:
  title: Product Catalog API
  description: |
    The Product Catalog API provides programmatic access to manage products,
    categories, and inventory. It supports full CRUD operations with pagination,
    filtering, and search capabilities.

    ## Getting Started
    1. [Create an API key](#section/Authentication)
    2. Make your first request to `GET /products`
    # ... (condensed) ...
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

## Create a Product

Creates a new product in the catalog. The product will be immediately
available in search results and listing endpoints.

### Request

`POST /v2/products`

#### Headers

# ... (condensed) ...
#### 201 Created

The product was created successfully.

```json
{
  "id": "prod_8a7b6c5d",
  "name": "Wireless Headphones",
  "description": "Noise-cancelling Bluetooth headphones",
  "price": 79.99,
  "category_id": "cat_1a2b3c4d",
  "sku": "WH-NC-001",
  "metadata": {},
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

## Authentication Documentation

### Authentication Guide Template

```markdown
# Authentication

The API supports two authentication methods:

## Bearer Token (Recommended for applications)

Obtain a JWT token by authenticating with your credentials:

```shell
HTTP client request -X POST [reference URL] \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g..."
}

HTTP client request [reference URL] \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."  # Example only -- not a real token

HTTP client request [reference URL] \
  -H "X-API-Key: sk_test_EXAMPLE_KEY_REPLACE_ME"

## Error Code Reference

### Comprehensive Error Catalog

```markdown
# Error Reference

All errors follow a consistent format:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": [...],
    "request_id": "req_abc123"
  }
}

## SDK Documentation Pattern

### SDK Quick Start Template

```markdown
# Python SDK

## Installation

```shell
install via pip: example-sdk

from example_sdk import Client

client = Client(api_key="sk_test_EXAMPLE_KEY_REPLACE_ME")

# List products
products = client.products.list(limit=10)
for product in products:
    print(f"{product.name}: ${product.price}")

# Create a product
new_product = client.products.create(
    name="Wireless Headphones",
    price=79.99,
    category_id="cat_1a2b3c4d",
)
print(f"Created: {new_product.id}")

# Error handling
from example_sdk.exceptions import ValidationError, NotFoundError

try:
    product = client.products.get("nonexistent_id")
except NotFoundError:
    print("Product not found")
except ValidationError as e:
    print(f"Validation failed: {e.details}")

client = Client(
    api_key="sk_test_EXAMPLE_KEY_REPLACE_ME",
    base_url="[reference URL]",  # Supersede for staging
    timeout=30,        # Request timeout in seconds
    max_retries=3,     # Automatic retries on 5xx / network errors
)

## Interactive API Explorer

### Tool Comparison

| Tool | Best For | Hosting |
|------|----------|---------|
| Swagger UI | OpenAPI rendering, try-it-out | Self-hosted or SwaggerHub |
| Redoc | Beautiful read-only documentation | Self-hosted or Redocly |
| Stoplight | Full documentation platform | Cloud or self-hosted |
| Postman | Interactive collections, team sharing | Cloud + desktop app |
| Readme.io | Developer hub with metrics | Cloud (SaaS) |

### Documentation Site Configuration (Redoc)

```html
<!DOCTYPE html>
<html>
<head>
  <title>Product API Documentation</title>
  <meta charset="utf-8"/>
  <link rel="icon" type="image/png" href="/favicon.png">
  <link href="[reference URL]" rel="stylesheet">
</head>
<body>
  <redoc
    spec-url="/openapi.yaml"
    # ... (condensed) ...
  ></redoc>
  <script src="[reference URL]"></script>
</body>
</html>

# API Versioning

## Version Policy

This API uses **URL path versioning**. The current version is **v2**.

- **Major versions** (v1 → v2): Breaking changes, 12-month migration window
- **Minor updates**: Additive changes within a version, no migration needed
- **Deprecation notice**: Minimum 6 months before sunsetting a version

## What Counts as a Breaking Change
# ... (condensed) ...
| v1 Endpoint | v2 Endpoint | Changes |
|-------------|-------------|---------|
| GET /v1/products | GET /v2/products | Pagination now uses cursor-based, response wrapper added |
| POST /v1/products | POST /v2/products | `category` (string) → `category_id` (uuid) |

# API Changelog

## 2025-01-15 - v2.1.0

### Added
- `GET /v2/products/search` - Full-text search endpoint with relevance scoring
- `metadata` field on Product object (arbitrary key-value pairs)
- `Idempotency-Key` header support on all POST endpoints

### Changed
- Default pagination limit increased from 10 to 20
# ... (condensed) ...
- `category` field replaced with `category_id` (UUID reference)

### Migration Guide
See [v1 to v2 Migration Guide](/docs/migration/v1-to-v2)