API Evangelist enhancements to the BNSF Reference Files API

overlay: 1.0.0
info:
  title: API Evangelist enhancements to the BNSF Reference Files API
  version: 1.0.0
extends: openapi/_original/bnsf-reference-files-openapi.json
x-generated: '2026-09-06'
x-method: generated
x-source: https://www.bnsf.com/ship-with-bnsf/support-services/customer-api/reference-files.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 Reference Files API
    description: 'Reference data used across BNSF freight operations and waybilling: event codes, station details,
      STCC commodity codes, hazardous-materials STCC detail, and Umler equipment characteristics.'
- 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: Reference Files
- 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/event-codes'].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: getV1EventCodes
    tags:
    - Reference Files
- target: $.paths['/v1/stations'].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: getV1Stations
    tags:
    - Reference Files
- target: $.paths['/v1/stcc'].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: getV1Stcc
    tags:
    - Reference Files
- target: $.paths['/v1/stcc/hazardous'].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: getV1StccHazardous
    tags:
    - Reference Files
- target: $.paths['/v1/umler'].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: postV1Umler
    tags:
    - Reference Files