REST API and OpenAPI Contract Design

Wrote docs/architecture/tasks/catalog-search-001/rest-api-design/rest-api-contract.md. Complete REST API specification defining OpenAPI 3.1 contracts, cursor-based pagination, RFC 9457 Problem Details error formats, and ETag conditional validation.

---
skill: rest-api-design
---

# REST API Contract: Product Catalog Service [REST-CAT-001]

## Summary

This specification defines the REST API contract and OpenAPI 3.1.0 specification for `catalog-service v2.2.0` under run ID `catalog-search-001`. It governs public catalog collection browsing (`GET /v1/products`) and item retrieval (`GET /v1/products/{product_id}`). It resolves the tension between mobile client simplicity and backend database performance by mandating opaque cursor-based pagination, strong ETag conditional caching (`If-None-Match` -> `304 Not Modified`), and RFC 9457 Problem Details error payloads, sustaining 2,500 peak requests/second within a 120 ms p95 latency budget.

## Detailed Description

Product catalog traffic represents 70% of total read traffic. High-concurrency reads during flash sales require strict cache-friendliness and database query bounding. Unbounded offset pagination causes severe database query degradation beyond page 50.

### Criteria and weights

| Criterion | Why it matters here | Weight | Source of the weight |
|---|---|---|---|
| Database Query Predictability | Offset pagination (`OFFSET N LIMIT M`) incurs O(N) index scans, causing latency spikes at 2,500 req/sec. | 0.35 | Alex Mercer (Product Eng Lead) |
| Cache Utilization & Network Efficiency | Static catalog metadata must be cached aggressively via CDN and edge proxies using ETags. | 0.30 | Sarah Chen (API Guild) |
| Latency SLA Compliance | p95 latency must remain <= 120 ms for search and <= 40 ms for details under peak load. | 0.20 | Request SLA specification |
| Standard Error Interoperability | Client error parsing must adhere to universal RFC 9457 specifications without bespoke JSON schemas. | 0.15 | API Guild standard |


### Comparison

| Design Dimension | Alternative A (Mobile Proposal) | Alternative B (Chosen Standard) | Justification |
|---|---|---|---|
| Pagination Style | Offset / Page (`page=5&limit=20`) | Cursor-based (`cursor=eyJpZ...&limit=20`) | Cursors guarantee constant-time O(1) index seeks regardless of page depth. |
| Cache Control | `no-store, no-cache` | `public, max-age=60, must-revalidate` + `ETag` | 304 Not Modified saves 90% bandwidth on repeat views; volatile stock moved to live endpoint. |
| Error Schema | Custom `{ code, message, error }` | RFC 9457 `application/problem+json` | Global standard compliant with corporate API governance. |


### Result

Alternative B is selected. Cursor-based pagination and ETag validation ensure consistent database performance and edge cacheability.

---

### Required Mechanisms

#### 1. Task Contract & Endpoint Definitions [MC-EP-01]

##### Resource: `GET /v1/products`
- **Query Parameters**:
  - `limit` (integer, optional): Items per page. Default: 20, Min: 1, Max: 100.
  - `cursor` (string, optional): Base64-encoded opaque cursor referencing `(sort_key, product_id)`.
  - `category` (string, optional): Category slug filter (e.g., `electronics`).
- **Response `200 OK`**:
  ```json

```json
  {
    "items": [
      {
        "id": "prod_01h8x9",
        "sku": "SKU-BLK-M",
        "title": "Ergonomic Mechanical Keyboard",
        "price_cents": 12900,
        "currency": "USD",
        "category": "electronics",
        "updated_at": "2026-09-15T12:00:00Z"
      }
    ],
    "pagination": {
      "next_cursor": "eyJzb3J0X2tleSI6MTI5MDAsImlkIjoicHJvZF8wMWh4OSJ9",
      "has_more": true
    }
  }

##### Resource: `GET /v1/products/{product_id}`
- **Path Parameter**: `product_id` (string, UUIDv4 or slug pattern `^prod_[a-z0-9]{6,16}$`).
- **Headers**:
  - Response Header: `ETag: W/"7f8a9b1c2d3e"` (Weak entity tag computed over entity JSON representation).
  - Response Header: `Cache-Control: public, max-age=60, stale-while-revalidate=30`.
- **Response `200 OK`**: Full product detail document.
- **Conditional Validation**:
  - Request with `If-None-Match: W/"7f8a9b1c2d3e"` matching current representation returns **`304 Not Modified`** with an empty body.

#### 2. Error Contract (RFC 9457 Problem Details) [MC-EC-01]
All 4xx and 5xx responses emit `Content-Type: application/problem+json`.

```json
{
  "type": "https://api.internal/errors/invalid-parameter",
  "title": "Invalid Request Parameter",
  "status": 400,
  "detail": "The 'limit' parameter must not exceed 100.",
  "instance": "/v1/products?limit=500",
  "invalid_params": [
    {
      "name": "limit",
      "reason": "Value 500 exceeds maximum allowed limit of 100."
    }
  ]
}

3. OpenAPI 3.1.0 Contract Definition [MC-OA-01]

• Strict validation: No un-typed objects, missing parameter schemas, or unmapped status codes.
• Security: Protected by bearer JWT authentication scopes (catalog:read).

Invariants and Contracts

Cursor-Based Pagination Guarantee [INV-REST-01]
  All collection endpoints returning list payloads must use opaque cursor tokens.
  Numeric page offset parameters (`page`, `offset`) are strictly rejected with HTTP 400.

Deterministic RFC 9457 Error Structure [INV-REST-02]
  Every non-2xx HTTP response must return an RFC 9457 problem JSON body containing
  the required properties: `type`, `title`, and `status`.

ETag Conditional Header Validation [INV-REST-03]
  Single-resource read endpoints must emit an `ETag` header and honor `If-None-Match`,
  returning HTTP 304 without payload body when hashes match.

Explicit Unknowns

• CDN cache purge event propagation latency across edge nodes on product updates (G-1).
• Dedicated live inventory stock endpoint path and rate limit specifications (G-2).

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against REST API architectural contracts:

• Pagination Check: PASS. Cursors enforced; offset/page parameters rejected.
• Cacheability Check: PASS. ETag computation and If-None-Match 304 handling fully specified.
• Error Standard: PASS. Compliant with RFC 9457 application/problem+json schema.
• OpenAPI Compliance: PASS. Conforms to OpenAPI 3.1.0 specification rules.

Open Decisions

• DEC-REST-01: Sarah Chen to specify path and contract for decoupled live inventory endpoint (e.g., /v1/products/{id}/stock) (Owner: Sarah Chen).

Next steps

1. Sarah Chen reviews OpenAPI 3.1.0 schema YAML with Mobile Engineering team leads.
2. Implement ETag middleware in services/catalog/api/middleware/etag.py.
3. Configure edge CDN cache policies to respect stale-while-revalidate=30.