API Evangelist enhancements to the BNSF Intermodal Hub Operations API

overlay: 1.0.0
info:
  title: API Evangelist enhancements to the BNSF Intermodal Hub Operations API
  version: 1.0.0
extends: openapi/_original/bnsf-intermodal-hub-operations-openapi.json
x-generated: '2026-09-06'
x-method: generated
x-source: https://www.bnsf.com/ship-with-bnsf/support-services/customer-api/intermodal-hub-operations.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 Intermodal Hub Operations API
    description: 'Intermodal facility operations across the BNSF hub network: dray bookings and dray plans, driver
      vehicle inspection reports, flips, lot locations, ingate and outgate registration and validation, pre-gate
      creation and cancellation, J1 gate receipts, pickup numbers, street en-route reporting, unit details, domestic
      empties and parking updates.'
- 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: Intermodal Hub Operations
- 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/dray-booking/open'].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: getV1DrayBookingOpen
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/dray-plan/list-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: postV1DrayPlanListUnits
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/dray-plan/initial/{equipmentInitial}/number/{equipmentNumber}'].delete
  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: deleteV1DrayPlanInitialByEquipmentInitialNumberByEquipmentNumber
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/dray-plan/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: getV1DrayPlanUnits
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/dray-plan/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: postV1DrayPlanUnits
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v2/dvir'].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: postV2Dvir
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/flips'].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: postV1Flips
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/hub'].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: getV1Hub
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v2/ingate'].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: postV2Ingate
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/ingate-management/current'].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: getV1IngateManagementCurrent
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v2/ingate/validate'].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: postV2IngateValidate
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/j1-receipts'].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: postV1J1Receipts
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v2/outgate'].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: postV2Outgate
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v2/outgate/validate'].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: postV2OutgateValidate
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/pickup-number'].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: postV1PickupNumber
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/pregate/in'].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: postV1PregateIn
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/pregate/in'].delete
  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: deleteV1PregateIn
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/pregate/out'].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: postV1PregateOut
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/pregate/out'].delete
  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: deleteV1PregateOut
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v2/street-en-route'].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: postV2StreetEnRoute
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v3/unit-details'].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: postV3UnitDetails
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v3/unit-details/domestic-empties'].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: getV3UnitDetailsDomesticEmpties
    tags:
    - Intermodal Hub Operations
- target: $.paths['/v1/update-parking'].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: postV1UpdateParking
    tags:
    - Intermodal Hub Operations