BNSF Diagnostics API

openapi: 3.0.0
info:
  title: BNSF Diagnostics API
  description: 'Operational diagnostics for the BNSF Customer API: an unauthenticated gateway health check and an analytic-event
    submission endpoint for usage telemetry.'
  termsOfService: http://www.bnsf.com/site-terms-of-use.html
  contact:
    name: BNSF Customer API
    email: CustomerAPI@bnsf.com
  version: '1.0'
servers:
- url: https://api.bnsf.com:6443
  description: Production
- url: https://api-trial.bnsf.com:6443
  description: Trial
paths:
  /healthcheck:
    get:
      tags:
      - Diagnostics
      summary: Check the status of the BNSF Customer API
      responses:
        '200':
          description: '**OK**


            The request has succeeded.'
          content:
            application/json:
              schema:
                type: string
                example: <status>ok</status>
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '504':
          $ref: '#/components/responses/504'
      operationId: getHealthcheck
  /v1/analytic-event:
    post:
      tags:
      - Diagnostics
      summary: 'Submit event data for analytical purposes. '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Generic_User_Provided_Details'
      responses:
        '200':
          description: '**OK**


            The request has succeeded.'
          content:
            application/json: {}
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '504':
          $ref: '#/components/responses/504'
      security:
      - Restricted: []
      operationId: postV1AnalyticEvent
components:
  schemas:
    Generic_User_Provided_Details:
      type: object
      required:
      - userProvidedEventTypeName
      - userProvidedStation333
      - userProvidedStationStateCode
      properties:
        userProvidedEventTypeName:
          type: string
          description: The name of an Event Type as provided by an internal or external user.
          example: Gate
        userProvidedStation333:
          type: string
          description: Name of a City, which is abbreviated from the City's Full Name as recognized across the Rail Industry,
            as provided by an internal or external user.
          example: GREFALLS
        userProvidedStationStateCode:
          type: string
          description: The State code for a given station defined by a standardized State code, as assigned by a national
            body such as the US Postal Service as provided by an internal or external user.
          example: MT
        userProvidedValues:
          type: array
          items:
            type: object
            required:
            - userProvidedDataItemName
            - userProvidedDataItemValueText
            properties:
              userProvidedDataItemName:
                type: string
                description: 'The symbolic name used to represent a unit of data that is provided by a user and is equivalent
                  to the key in a key-value pair.  '
                example: Lane
              userProvidedDataItemValueText:
                type: string
                description: The actual data content that is provided by a user and is equivalent to the value in a key-value
                  pair.  This may be alpha or numeric in content.
                example: A12
  responses:
    '400':
      description: '**Bad Request**


        The request could not be understood by the server due to incorrect syntax. Do not repeat the request without modifications.'
    '401':
      description: '**Unauthorized**


        Indicates that the request requires user authentication information. The client MAY repeat the request with a suitable
        Authorization.'
    '403':
      description: "Unauthorized request. Here are the most common causes:\n    \n* You are getting 403 Access Denied.\n\n\
        \   * It takes a few days for us to get you set up after you register. When set up is complete, you will receive an\
        \ email letting you know. If you have not received the email, please wait up to five business days. Let us know via\
        \ API Support if you still have not received the email after five business days.\n   * You can also get this error\
        \ if your certificate is not configured properly on your side. Please review the Mutual Authentication in the Getting\
        \ Started section of our documentation.\n\n\n* You are getting 403 \"message\": \"Insufficient privileges\" when accessing\
        \ a restricted service for which you do not have permission. You can use our Registration form to request access.\
        \ Be sure to explain the situation in the \"Please explain how you intend to use the API\" field.\n"
    '404':
      description: '**Not Found**


        The server cannot find the requested resource (URI). That is, the address of the endpoint in your request does not
        exist. Please consult the documentation.'
    '405':
      description: '**Method Not Allowed**


        The request HTTP method is known by the server but has been disabled and cannot be used for that resource. For example,
        you may be using GET when POST is required. Please consult the documentation.'
    '429':
      description: "**Too Many Requests**\n\nThe BNSF API Gateway enforces rate limits to maintain application security and\
        \ performance.  Current rate limits are set as follows:\n* 1 API Request Per Second, Per Partner, Per Service\n* 15\
        \ API Requests Per Minute, Per Partner, Per Service\n* 100 API Request Per Minute, Per Service\n \nWhen requests exceed\
        \ these limits the API Gateway will return a **429 Too Many Requests** error response. Upon receiving such exceptions,\
        \ you can resubmit failed requests in a rate-limited manner, complying with the API Gateway throttle limits. "
    '500':
      description: '**Internal Server Error**


        The server encountered an unexpected condition which prevented it from fulfilling the request. This is always a problem
        on the server side. Our internal support systems will be made aware.'
    '504':
      description: '**Gateway Timeout**


        The server is acting as a gateway and cannot get a response in time for a request. Wait about one minute then try
        again.'
  requestBodies: {}
  securitySchemes:
    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/'
tags:
- name: Diagnostics
security:
- MutualTLS: []
x-generated-from: openapi/_original/bnsf-diagnostics-openapi.json