API Design — Contract-First REST, Errors & Versioning

Summary. REST fits here. The consumers are a mobile app and outside partners, and the work is resource CRUD over orders, so broad client reach matters more than flexible queries. The draft has 9 problems. Six of them, marked blocker, would be expensive or unsafe to fix after partners integrate. Nothing has shipped yet, so every fix below is free now. The same changes on a live API would be breaking and would need a new version.

Findings

Proposed contract (OpenAPI excerpt, write this before the handlers)

openapi: 3.1.0
info: { title: Orders API, version: "1" }
paths:
  /v1/orders:
    post:
      summary: Create an order for the authenticated customer
      parameters:
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 255 } }
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateOrder" }
      responses:
        "201": { description: Created, headers: { Location: { schema: { type: string } } } }
        "401": { $ref: "#/components/responses/Problem" }
        "409": { $ref: "#/components/responses/Problem" }
        "422": { $ref: "#/components/responses/Problem" }
    get:
      summary: List the authenticated customer's orders
      parameters:
        - { name: page_size, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
        - { name: page_token, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { $ref: "#/components/schemas/OrderStatus" } }
      responses:
        "200": { description: A page of orders with next_page_token }
  /v1/orders/{order_id}:
    get:
      responses:
        "200": { description: The order (only if it belongs to the caller), headers: { ETag: { schema: { type: string } } } }
        "404": { $ref: "#/components/responses/Problem" }
  /v1/orders/{order_id}/cancellations:
    post:
      parameters:
        - { name: If-Match, in: header, required: true, schema: { type: string } }
      responses:
        "201": { description: Cancellation recorded }
        "409": { description: Order can no longer be canceled (already shipped) }
        "412": { description: Order changed since it was read }
        "428": { description: If-Match missing }

CreateOrder holds items[] (sku, qty with a max), currency and a payment_method_id. It has no user_id, and fields that aren't on the allow-list are rejected, which blocks mass assignment.

Error envelope (every error path)

{
  "type": "https://api.example.com/errors/out-of-stock",
  "title": "Item out of stock",
  "status": 422,
  "detail": "SKU TSHIRT-M has 1 unit left, 2 requested.",
  "code": "OUT_OF_STOCK",
  "errors": [{ "field": "items[0].qty", "code": "EXCEEDS_STOCK" }],
  "traceId": "0af7651a..."
}

Stack traces, SQL and class names are logged on the server under traceId and are never returned to the client.

Decisions to confirm

Card data. cardToken in the order body suggests payment happens inside order creation. If you keep it, the idempotency key is what prevents a double charge on retry. Confirm which provider token format you are accepting.

Cancel as a sub-resource or a state change. POST /orders/{id}/cancellations keeps a record of who canceled and why. PATCH /orders/{id} {"status":"canceled"} also works if no audit record is needed.

Rate limiting. Return 429 with Retry-After per token, and use an explicit CORS allow-list if a web client is ever added.

Next steps

1. Write the full openapi.yaml from the excerpt and review it with the mobile and partner teams before any handler exists.
2. Add a spec linter (for example Spectral) to CI so drift between spec and code fails the build.
3. Implement handlers against the spec. Put the per-order ownership check in one place that every /{order_id} route goes through.
4. Learning capture: nothing project-specific came up beyond the defaults, so no learnings/ entry was written.