openapi: 3.1.0
info:
  title: AtlasBridge Orders API
  version: 1.0.0
  summary: Synthetic API documentation sample
  description: |
    A complete, fictional API used to demonstrate contract-first documentation.
    AtlasBridge is not a real client or production service.
servers:
  - url: https://api.example.invalid/v1
    description: Non-routable documentation example
security:
  - oauth2: [orders:read, orders:write]
paths:
  /orders:
    post:
      operationId: createOrder
      summary: Create an order
      description: Creates one order. Retrying with the same Idempotency-Key and identical body returns the original result.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrder'
            examples:
              steelCoilOrder:
                value:
                  customerReference: PO-2026-0042
                  currency: EUR
                  lines:
                    - sku: COIL-S235JR-1250-2.0
                      quantity: 24.5
                      unit: TNE
      responses:
        '201':
          description: Order created
          headers:
            X-Correlation-Id:
              $ref: '#/components/headers/CorrelationId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/Problem'
        '401':
          $ref: '#/components/responses/Problem'
        '409':
          description: Idempotency key reused with a different request body, or a business-key conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          $ref: '#/components/responses/RateLimited'
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Retrieve an order
      security:
        - oauth2: [orders:read]
      parameters:
        - $ref: '#/components/parameters/OrderId'
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        '200':
          description: Current order representation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          $ref: '#/components/responses/Problem'
webhooks:
  orderStatusChanged:
    post:
      summary: Order status changed
      description: Receivers verify X-Atlas-Signature against the unmodified request body and reject timestamps older than five minutes.
      parameters:
        - name: X-Atlas-Signature
          in: header
          required: true
          schema: { type: string }
        - name: X-Atlas-Timestamp
          in: header
          required: true
          schema: { type: string, format: date-time }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [eventId, occurredAt, type, data]
              properties:
                eventId: { type: string, format: uuid }
                occurredAt: { type: string, format: date-time }
                type: { const: order.status_changed }
                data: { $ref: '#/components/schemas/Order' }
      responses:
        '204': { description: Event accepted }
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.invalid/oauth/token
          scopes:
            orders:read: Read orders
            orders:write: Create and update orders
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: A client-generated UUID retained for 24 hours.
      schema: { type: string, format: uuid }
    CorrelationId:
      name: X-Correlation-Id
      in: header
      required: false
      description: A caller-provided trace identifier. The service returns the effective value.
      schema: { type: string, maxLength: 100 }
    OrderId:
      name: orderId
      in: path
      required: true
      schema: { type: string, format: uuid }
  headers:
    CorrelationId:
      description: Effective trace identifier
      schema: { type: string }
  responses:
    Problem:
      description: Request could not be processed
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
    RateLimited:
      description: Rate limit exceeded. Retry after the indicated delay.
      headers:
        Retry-After:
          description: Delay in seconds
          schema: { type: integer, minimum: 1 }
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
  schemas:
    CreateOrder:
      type: object
      additionalProperties: false
      required: [customerReference, currency, lines]
      properties:
        customerReference: { type: string, minLength: 1, maxLength: 50 }
        currency: { type: string, pattern: '^[A-Z]{3}$' }
        lines:
          type: array
          minItems: 1
          maxItems: 500
          items:
            type: object
            additionalProperties: false
            required: [sku, quantity, unit]
            properties:
              sku: { type: string, minLength: 1, maxLength: 80 }
              quantity: { type: number, exclusiveMinimum: 0 }
              unit: { type: string, enum: [PCE, KGM, TNE, MTR] }
    Order:
      allOf:
        - $ref: '#/components/schemas/CreateOrder'
        - type: object
          required: [id, status, createdAt]
          properties:
            id: { type: string, format: uuid }
            status: { type: string, enum: [RECEIVED, VALIDATED, CONFIRMED, FULFILLED, REJECTED] }
            createdAt: { type: string, format: date-time }
    Problem:
      type: object
      required: [type, title, status, correlationId]
      properties:
        type: { type: string, format: uri-reference }
        title: { type: string }
        status: { type: integer, minimum: 400, maximum: 599 }
        detail: { type: string }
        correlationId: { type: string }
        errors:
          type: array
          items:
            type: object
            required: [code, message]
            properties:
              code: { type: string }
              field: { type: string }
              message: { type: string }
