openapi: 3.0.0
info:
  title: Prototype City Pairs API
  description: >-
    Prototype project for GSA API strategy.
  version: 0.0.0
paths:
  /airfares:
    get:
      summary: Negotiated airfares
      description: |
        This endpoint returns negotiated airfaires.
      parameters:
        - name: award_year
          in: query
          description: 'Year of airfare award. Example: ''2017'''
          required: true
          schema:
            type: string
            format: string
        - name: origin_airport_abbrev
          in: query
          description: >-
            Origin airport abbreviation. Example: 'ABQ'. Must include either
            this or the destination airport abbreviation.
          required: false
          schema:
            type: string
            format: string
        - name: destination_airport_abbrev
          in: query
          description: >-
            Destination airport abbreviation. Example: 'BWI'. Must include
            either this or the origination airport abbreviation.
          required: false
          schema:
            type: string
            format: string
      tags:
        - name: Airfares
      responses:
        '200':
          description: An array of airfares
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Airfare'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  '/airfares/{id}':
    get:
      summary: Individual airfare by ID
      description: >
        This endpoint returns one airfare by ID. (This is just for demonstration
        purpose. For City Pairs, the ID does not have meaning.)
      parameters:
        - name: id
          in: path
          description: Unique identifier
          required: true
          schema:
            type: integer
            format: int32
      tags:
        - name: Airfares
      responses:
        '200':
          description: An array of airfares
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Airfare'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
servers:
  - url: 'https://api.gsa.gov/travel/citypairs/v0'
components:
  schemas:
    Airfare:
      type: object
      properties:
        ID:
          type: integer
          description: Generated unique identifier.
        ITEM_NUM:
          type: string
          description: Item number.
        AWARD_YEAR:
          type: string
          description: Award Year.
        ORIGIN_AIRPORT_ABBREV:
          type: string
          description: Origin Airport Abbreviation.
        DESTINATION_AIRPORT_ABBREV:
          type: string
          description: Destinatoin Airport Abbreviation.
        ORIGIN_CITY_NAME:
          type: string
          description: Original City Name.
        ORIGIN_STATE:
          type: string
          description: Origin State.
        ORIGIN_COUNTRY:
          type: string
          description: Origin Country.
        DESTINATION_CITY_NAME:
          type: string
          description: Destination City Name.
        DESTINATION_STATE:
          type: string
          description: Destination State.
        DESTINATION_COUNTRY:
          type: string
          description: Destination Country.
        AIRLINE_ABBREV:
          type: string
          description: Airline Abbreviation.
        AWARDED_SERV:
          type: string
          description: Awarded Serv.
        PAX_COUNT:
          type: string
          description: PAX Count.
        YCA_FARE:
          type: integer
          description: YCA Fare.
        XCA_FARE:
          type: integer
          description: XCA Fare.
        BUSINESS_FARE:
          type: integer
          description: Business Fare.
        ORIGIN_AIRPORT_LOCATION:
          type: string
          description: Origin Airport Location.
        DESTINATION_AIRPORT_LOCATION:
          type: string
          description: Destination Airport Location.
        ORIGIN_CITY_STATE_AIRPORT:
          type: string
          description: Origin City State Airport.
        DESTINATION_CITY_STATE_AIRPORT:
          type: string
          format: date-time
          description: Destination City State Airport.
        EFFECTIVE_DATE:
          type: string
          format: date-time
          description: Expiration Date.
        EXPIRATION_DATE:
          type: string
          format: date-time
          description: Expiration Date.
    Error:
      type: object
      properties:
        message:
          type: string
        required_fields:
          type: string
        example:
          type: string
  securitySchemes:
    ApiKeyAuth:        # arbitrary name for the security scheme
      type: apiKey
      in: header       # can be "header", "query" or "cookie"
      name: X-API-KEY  # name of the header, query parameter or cookie
      default: DEMO_KEY
security:
  - ApiKeyAuth: []