API Evangelist enhancements to the BNSF Tracing API

overlay: 1.0.0
info:
  title: API Evangelist enhancements to the BNSF Tracing API
  version: 1.0.0
extends: openapi/_original/bnsf-trace-openapi.json
x-generated: '2026-09-06'
x-method: generated
x-source: https://www.bnsf.com/ship-with-bnsf/support-services/customer-api/trace.json
x-note: 'Captures every change API Evangelist made between the verbatim harvested document in openapi/_original/
  and the working document in openapi/. No BNSF-authored field is altered: the overlay only fills in metadata BNSF
  left empty (title, description, tags, operationIds, securitySchemes) and adds the Trial server BNSF documents
  in prose.'
actions:
- target: $.info
  description: BNSF publishes this document with an empty info.title and info.description. Supply the service name
    BNSF uses for it in its own API Catalog, and a description written from that catalog entry.
  update:
    title: BNSF Tracing API
    description: Real-time shipment tracing across automotive VINs, carload railcars, intermodal units and unit
      trains on the BNSF network, including trip plans and significant-event history. Bulk POST endpoints accept
      up to 300 units per request; list endpoints page at a default and maximum of 2,000 records.
- target: $.servers
  description: The published document names only the Production host. BNSF documents a Trial host on the same port
    in Getting Started; add it so the trial environment is machine-readable.
  update:
  - url: https://api.bnsf.com:6443
    description: Production
  - url: https://api-trial.bnsf.com:6443
    description: Trial
- target: $.tags
  description: The published document declares no tags and labels every operation "Requests". Replace with the service
    name BNSF uses in its Catalog.
  update:
  - name: Tracing
- target: $.components.securitySchemes
  description: The published document declares no securitySchemes at all, while referencing a "Restricted" scheme
    in security requirements. Define both schemes from the Getting Started and API Support pages.
  update:
    MutualTLS:
      type: mutualTLS
      description: 'BNSF requires certificate-based mutual TLS (two-way authentication). Client certificates must
        be x509 PEM, issued by a recognised public Certificate Authority (Domain Validation, Organization Validation,
        Extended Validation or S/MIME), effective no longer than 36 months, with Extended Key Usage including Client
        Authentication (OID 1.3.6.1.5.5.7.3.2). Self-signed, private, Let''s Encrypt, webCARES and Cloudflare-issued
        certificates are not accepted. Source: https://www.bnsf.com/ship-with-bnsf/support-services/customer-api/getting-started/'
    Restricted:
      type: mutualTLS
      description: 'Restricted Service. The same client certificate applies, but the certificate must additionally
        be authorised for this service by BNSF API Support. Unauthorised callers receive 403 "Insufficient privileges".
        Restricted Services are only available in the Production environment. Source: https://www.bnsf.com/ship-with-bnsf/support-services/customer-api/support/'
- target: $.security
  description: Declare the document-level requirement of mutual TLS, which BNSF states in prose but omits from the
    machine-readable contract.
  update:
  - MutualTLS: []
- target: $.paths['/v1/trip-plan-automotive'].get
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: getV1TripPlanAutomotive
    tags:
    - Tracing
- target: $.paths['/v1/vins'].post
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: postV1Vins
    tags:
    - Tracing
- target: $.paths['/v1/vin-details'].get
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: getV1VinDetails
    tags:
    - Tracing
- target: $.paths['/v1/vin-inspections'].get
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: getV1VinInspections
    tags:
    - Tracing
- target: $.paths['/v1/cars'].get
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: getV1Cars
    tags:
    - Tracing
- target: $.paths['/v1/cars'].post
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: postV1Cars
    tags:
    - Tracing
- target: $.paths['/v1/carload-consist'].get
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: getV1CarloadConsist
    tags:
    - Tracing
- target: $.paths['/v1/trip-plan-carload'].get
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: getV1TripPlanCarload
    tags:
    - Tracing
- target: $.paths['/v1/trip-plan-intermodal'].get
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: getV1TripPlanIntermodal
    tags:
    - Tracing
- target: $.paths['/v1/units'].get
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: getV1Units
    tags:
    - Tracing
- target: $.paths['/v1/units'].post
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: postV1Units
    tags:
    - Tracing
- target: $.paths['/v1/trains'].get
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: getV1Trains
    tags:
    - Tracing
- target: $.paths['/v1/ag-trains'].post
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: postV1AgTrains
    tags:
    - Tracing
- target: $.paths['/v1/coal-trains'].post
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: postV1CoalTrains
    tags:
    - Tracing
- target: $.paths['/v1/ip-trains'].post
  description: The published operation has no operationId and is tagged "Requests". Assign a stable operationId
    derived from method and path, and retag to the service.
  update:
    operationId: postV1IpTrains
    tags:
    - Tracing