openapi: 3.0.2
info:
  title: My API
  version: 1.0.0
servers:
  - url: 'https://my-api.example'
paths:
  /api/traveler:
    get:
      tags:
        - traveler
      summary: Retrieve all travelers.
      responses:
        '200':
          description: List of all travelers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Traveler'
        '401':
          $ref: '#/components/responses/Unathenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags:
        - traveler
      summary: Create a traveler.
      description: |-
        Supply the traveler data to create a traveler in the API proxy.

        Both residency and billing addresses are required.

        Note the `id` field in the response and store it in the customer record for future use in quote requests, as well as the billing address `id` for future use in purchase requests.
      requestBody:
        $ref: '#/components/requestBodies/TravelerCreate'
      responses:
        '201':
          description: Displays the new traveler data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Traveler'
              example:
                value:
                  type: Adult
                  prefix: Mrs.
                  first_name: Nicolette
                  middle_name: ''
                  last_name: Little
                  suffix: ''
                  date_of_birth: '2000-01-01'
                  gender: F
                  email: Nicolette.Little@example.net
                  mobile_phone: 234-567-8901
                  office_phone: null
                  home_phone: null
                  updated_at: '2020-07-10 20:27:05'
                  created_at: '2020-07-10 20:27:05'
                  id: 1
                  addresses:
                    residency:
                      id: 1
                      created_at: '2020-07-10T20:27:05.000000Z'
                      updated_at: '2020-07-10T20:27:05.000000Z'
                      traveler_id: 1
                      address_1: 08499 Vesta Extensions
                      address_2: null
                      address_3: null
                      locality: Strosinborough
                      region: AZ
                      postal_code: 79147-3723
                      country: USA
                    billing:
                      id: 2
                      created_at: '2020-07-10T20:27:05.000000Z'
                      updated_at: '2020-07-10T20:27:05.000000Z'
                      traveler_id: 1
                      address_1: 20237 Friesen Ports
                      address_2: null
                      address_3: null
                      locality: New Cathyberg
                      region: AZ
                      postal_code: 09718-6581
                      country: USA
        '401':
          $ref: '#/components/responses/Unathenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ErrorValidation'
  '/api/traveler/{traveler}':
    get:
      tags:
        - traveler
      summary: Display the specified traveler.
      parameters:
        - name: traveler
          in: path
          description: Traveler ID.
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/TravelerShow'
        '401':
          $ref: '#/components/responses/Unathenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      tags:
        - traveler
      summary: Update the specified traveler.
      description: |-
        You can pass all the data or only the data you wish to change. Anything provided will overwrite data stored in the API proxy.

        If updating an address, include an integer `id` with the address ID from when the traveler was created.
      parameters:
        - name: traveler
          in: path
          description: Traveler ID.
          required: true
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/TravelerUpdate'
      responses:
        '200':
          description: Displays the new traveler data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Traveler'
              example:
                value:
                  type: Child
                  prefix: Mrs.
                  first_name: Johnny
                  middle_name: ''
                  last_name: Little
                  suffix: ''
                  date_of_birth: '2000-01-01'
                  gender: F
                  email: Nicolette.Little@example.net
                  mobile_phone: 234-567-8901
                  office_phone: null
                  home_phone: null
                  updated_at: '2020-07-10 20:27:05'
                  created_at: '2020-07-10 20:27:05'
                  id: 1
                  addresses:
                    residency:
                      id: 1
                      created_at: '2020-07-10T20:27:05.000000Z'
                      updated_at: '2020-07-10T20:27:05.000000Z'
                      traveler_id: 1
                      address_1: 123 Anystreet
                      address_2: null
                      address_3: null
                      locality: Strosinborough
                      region: AZ
                      postal_code: 79147-3723
                      country: USA
                    billing:
                      id: 2
                      created_at: '2020-07-10T20:27:05.000000Z'
                      updated_at: '2020-07-10T20:27:05.000000Z'
                      traveler_id: 1
                      address_1: 20237 Friesen Ports
                      address_2: null
                      address_3: null
                      locality: New Cathyberg
                      region: AZ
                      postal_code: 09718-6581
                      country: USA
        '401':
          $ref: '#/components/responses/Unathenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ErrorValidation'
  /api/trip:
    get:
      tags:
        - trip
      summary: Retrieve all trips.
      responses:
        '200':
          description: List of all trips
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trip'
        '401':
          $ref: '#/components/responses/Unathenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags:
        - trip
      summary: Create a trip.
      description: Note the `id` field in the response and store it in the trip record for future use in quote requests.
      requestBody:
        $ref: '#/components/requestBodies/TripCreate'
      responses:
        '201':
          description: Displays the new trip data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trip'
        '401':
          $ref: '#/components/responses/Unathenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ErrorValidation'
  '/api/trip/{trip}':
    get:
      tags:
        - trip
      summary: Display the specified trip.
      parameters:
        - name: trip
          in: path
          description: Trip ID.
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/TripShow'
        '401':
          $ref: '#/components/responses/Unathenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      tags:
        - trip
      summary: Update the specified trip.
      description: You can pass all the data or only the data you wish to change. Anything provided will overwrite data stored in the API proxy.
      parameters:
        - name: trip
          in: path
          description: Trip ID.
          required: true
          schema:
            type: string
      requestBody:
        $ref: '#/components/requestBodies/TripUpdate'
      responses:
        '200':
          $ref: '#/components/responses/TripUpdate'
        '401':
          $ref: '#/components/responses/Unathenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ErrorValidation'
components:
  schemas:
    TripItemLocation:
      type: object
      properties:
        type:
          description: Location type
          enum:
            - Origin
            - Destination
            - ActivityLocation
          type: string
        area_type:
          description: Location area type
          enum:
            - IATAAirport
            - ISOCountry
            - ISOState
          type: string
        value:
          description: Location code
          type: string
    ValidationError:
      type: object
      properties:
        message:
          type: string
          example: The given data was invalid.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            field:
              - Something is wrong with this field.
    Traveler:
      type: object
      properties:
        id:
          description: Traveler ID
          format: int64
          type: number
          readOnly: true
        created_at:
          description: Timestamp when the trip was created
          format: date-time
          type: string
          readOnly: true
        updated_at:
          description: Timestamp when the trip was updated
          format: date-time
          type: string
          readOnly: true
        type:
          description: Traveler type
          enum:
            - Individual
            - Adult
            - Child
            - YoungAdult
            - Senior
            - Infant
            - Spouse
          default: Adult
          type: string
        prefix:
          description: Name prefix
          type: string
        first_name:
          description: First name
          type: string
        middle_name:
          description: Middle name
          type: string
        last_name:
          description: Last name
          type: string
        suffix:
          description: Name suffix
          type: string
        date_of_birth:
          description: Birth date
          format: date
          type: string
        gender:
          description: Gender
          enum:
            - M
            - F
          type: string
        email:
          description: Email
          type: string
        mobile_phone:
          description: Mobile phone number
          type: string
        office_phone:
          description: Office phone numbe
          type: string
        home_phone:
          description: Home phone number
          type: string
        addresses:
          description: Residency and billing addresses
          type: object
          properties:
            residency:
              type: object
              properties:
                '':
                  $ref: '#/components/schemas/Address'
            billing:
              type: object
              properties:
                '':
                  $ref: '#/components/schemas/Address'
      example:
        type: Adult
        prefix: Mrs.
        first_name: Nicolette
        middle_name: ''
        last_name: Little
        suffix: ''
        date_of_birth: '2000-01-01'
        gender: F
        email: Nicolette.Little@example.net
        mobile_phone: 234-567-8901
        office_phone: null
        home_phone: null
        updated_at: '2020-07-10 20:27:05'
        created_at: '2020-07-10 20:27:05'
        id: 1
        addresses:
          residency:
            id: 1
            created_at: '2020-07-10T20:27:05.000000Z'
            updated_at: '2020-07-10T20:27:05.000000Z'
            traveler_id: 1
            address_1: 08499 Vesta Extensions
            address_2: null
            address_3: null
            locality: Strosinborough
            region: AZ
            postal_code: 79147-3723
            country: USA
          billing:
            id: 2
            created_at: '2020-07-10T20:27:05.000000Z'
            updated_at: '2020-07-10T20:27:05.000000Z'
            traveler_id: 1
            address_1: 20237 Friesen Ports
            address_2: null
            address_3: null
            locality: New Cathyberg
            region: AZ
            postal_code: 09718-6581
            country: USA
    Trip:
      type: object
      properties:
        id:
          description: Trip ID
          format: int64
          type: number
          readOnly: true
        created_at:
          description: Timestamp when the trip was created
          format: date-time
          type: string
          readOnly: true
        updated_at:
          description: Timestamp when the trip was updated
          format: date-time
          type: string
          readOnly: true
        type:
          description: Type of trip
          enum:
            - RT
            - OW
            - MT
          default: RT
          type: string
        currency:
          description: ISO currency code
          default: USD
          type: string
        total_price:
          description: Total trip cost
          default: 0
          format: float
          type: number
        trip_items:
          description: All parts of the trip.
          default: []
          type: array
          items:
            $ref: '#/components/schemas/TripItem'
      example:
        type: RT
        total_price: 1700
        currency: USD
        updated_at: '2020-07-10 20:26:24'
        created_at: '2020-07-10 20:26:24'
        id: 1
        trip_items:
          - id: 1
            created_at: '2020-07-10T20:26:24.000000Z'
            updated_at: '2020-07-10T20:26:24.000000Z'
            trip_id: 1
            start: '2020-12-20 00:00:00'
            end: '2021-01-01 00:00:00'
            type: Non-refundable
            locations:
              - type: Origin
                area_type: IATAAirport
                value: ORD
              - type: Destination
                area_type: IATAAirport
                value: JFK
          - id: 2
            created_at: '2020-07-10T20:26:24.000000Z'
            updated_at: '2020-07-10T20:26:24.000000Z'
            trip_id: 1
            start: '2021-01-02 00:00:00'
            end: '2021-02-01 00:00:00'
            type: Non-refundable
            locations:
              - type: Origin
                area_type: IATAAirport
                value: JFK
              - type: Destination
                area_type: IATAAirport
                value: ORD
    TripItem:
      type: object
      properties:
        id:
          description: Trip Item ID
          format: int64
          type: number
          readOnly: true
        created_at:
          description: Timestamp when the trip was created
          format: date-time
          type: string
          readOnly: true
        updated_at:
          description: Timestamp when the trip was updated
          format: date-time
          type: string
          readOnly: true
        trip_id:
          description: Trip ID
          format: int64
          type: number
          readOnly: true
        start:
          description: Trip item start time
          format: date-time
          type: string
        end:
          description: Trip item end time
          format: date-time
          type: string
        type:
          description: Trip type
          enum:
            - Refundable
            - Non-refundable
          default: Refundable
          type: string
        locations:
          description: Array of locations
          default: '[]'
          type: array
          items:
            $ref: '#/components/schemas/TripItemLocation'
          example:
            - type: Origin
              area_type: IATAAirport
              value: ORD
            - type: ActivityLocation
              area_type: IATAAirport
              value: JFK
            - type: Destination
              area_type: IATAAirport
              value: MDW
    Address:
      type: object
      properties:
        id:
          description: Address ID
          format: int64
          type: number
          readOnly: true
        created_at:
          description: Timestamp when address was created
          format: date-time
          type: string
        updated_at:
          description: Timestamp when address was updated
          format: date-time
          type: string
        traveler_id:
          description: Traveler ID who owns this address
          format: int64
          type: number
          readOnly: true
        address_1:
          description: Address line 1
          type: string
        address_2:
          description: Address line 2
          type: string
        address_3:
          description: Address line 3
          type: string
        locality:
          description: City
          type: string
        region:
          description: ISO state/province code
          type: string
        postal_code:
          description: Zip or postal code
          type: string
        country:
          description: 3-letter ISO country code
          type: string
  responses:
    TripUpdate:
      description: Displays the trip data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Trip'
          example:
            type: RT
            total_price: 1200
            currency: USD
            updated_at: '2020-07-12 20:26:24'
            created_at: '2020-07-10 20:26:24'
            id: 1
            trip_items:
              - id: 1
                created_at: '2020-07-10T20:26:24.000000Z'
                updated_at: '2020-07-10T20:26:24.000000Z'
                trip_id: 1
                start: '2020-12-20 00:00:00'
                end: '2021-01-01 00:00:00'
                type: Non-refundable
                locations:
                  - type: Origin
                    area_type: IATAAirport
                    value: ORD
                  - type: Destination
                    area_type: IATAAirport
                    value: JFK
              - id: 2
                created_at: '2020-07-10T20:26:24.000000Z'
                updated_at: '2020-07-10T20:26:24.000000Z'
                trip_id: 1
                start: '2021-01-02 00:00:00'
                end: '2021-02-01 00:00:00'
                type: Non-refundable
                locations:
                  - type: Origin
                    area_type: IATAAirport
                    value: JFK
                  - type: Destination
                    area_type: IATAAirport
                    value: ORD
    TripShow:
      description: Displays the trip data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Trip'
          example:
            type: RT
            total_price: 1700
            currency: USD
            updated_at: '2020-07-10 20:26:24'
            created_at: '2020-07-10 20:26:24'
            id: 1
            trip_items:
              - id: 1
                created_at: '2020-07-10T20:26:24.000000Z'
                updated_at: '2020-07-10T20:26:24.000000Z'
                trip_id: 1
                start: '2020-12-20 00:00:00'
                end: '2021-01-01 00:00:00'
                type: Non-refundable
                locations:
                  - type: Origin
                    area_type: IATAAirport
                    value: ORD
                  - type: Destination
                    area_type: IATAAirport
                    value: JFK
              - id: 2
                created_at: '2020-07-10T20:26:24.000000Z'
                updated_at: '2020-07-10T20:26:24.000000Z'
                trip_id: 1
                start: '2021-01-02 00:00:00'
                end: '2021-02-01 00:00:00'
                type: Non-refundable
                locations:
                  - type: Origin
                    area_type: IATAAirport
                    value: JFK
                  - type: Destination
                    area_type: IATAAirport
                    value: ORD
    Forbidden:
      description: Insufficient permission.
      content:
        application/json:
          schema:
            type: string
            example:
              message: Forbidden.
    ErrorValidation:
      description: The request contained bad data.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    Unathenticated:
      description: Invalid or no credentials supplied.
      content:
        application/json:
          schema:
            type: string
            example:
              message: Unauthenticated.
    TravelerShow:
      description: Displays the traveler data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Traveler'
          example:
            type: Adult
            prefix: Mrs.
            first_name: Nicolette
            middle_name: ''
            last_name: Little
            suffix: ''
            date_of_birth: '2000-01-01'
            gender: F
            email: Nicolette.Little@example.net
            mobile_phone: 234-567-8901
            updated_at: '2020-07-10 20:27:05'
            created_at: '2020-07-10 20:27:05'
            id: 1
            addresses:
              residency:
                id: 1
                created_at: '2020-07-10T20:27:05.000000Z'
                updated_at: '2020-07-10T20:27:05.000000Z'
                traveler_id: 1
                address_1: 08499 Vesta Extensions
                address_2: null
                address_3: null
                locality: Strosinborough
                region: AZ
                postal_code: 79147-3723
                country: USA
              billing:
                id: 2
                created_at: '2020-07-10T20:27:05.000000Z'
                updated_at: '2020-07-10T20:27:05.000000Z'
                traveler_id: 1
                address_1: 20237 Friesen Ports
                address_2: null
                address_3: null
                locality: New Cathyberg
                region: AZ
                postal_code: 09718-6581
                country: USA
  requestBodies:
    TripUpdate:
      description: Trip data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Trip'
          example:
            type: RT
            total_price: 1200
    TravelerUpdate:
      description: Traveler data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Traveler'
          example:
            type: Child
            first_name: Johnny
            addresses:
              residency:
                id: 1
                street: 123 Anystreet
    TravelerCreate:
      description: Traveler data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Traveler'
          example:
            type: Adult
            prefix: Mrs.
            first_name: Nicolette
            middle_name: ''
            last_name: Little
            suffix: ''
            date_of_birth: '2000-01-01'
            gender: F
            email: Nicolette.Little@example.net
            mobile_phone: 234-567-8901
            addresses:
              residency:
                address_1: 08499 Vesta Extensions
                address_2: null
                address_3: null
                locality: Strosinborough
                region: AZ
                postal_code: 79147-3723
                country: USA
              billing:
                address_1: 20237 Friesen Ports
                address_2: null
                address_3: null
                locality: New Cathyberg
                region: AZ
                postal_code: 09718-6581
                country: USA
    TripCreate:
      description: Trip data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Trip'
          example:
            type: RT
            total_price: 1700
            currency: USD
            trip_items:
              - start: '2020-12-20'
                end: '2021-01-01'
                type: Non-refundable
                locations:
                  - type: Origin
                    area_type: IATAAirport
                    value: ORD
                  - type: Destination
                    area_type: IATAAirport
                    value: JFK
              - start: '2021-01-02'
                end: '2021-02-01'
                type: Non-refundable
                locations:
                  - type: Origin
                    area_type: IATAAirport
                    value: JFK
                  - type: Destination
                    area_type: IATAAirport
                    value: ORD
  securitySchemes:
    apiKey:
      type: http
      description: API token
      scheme: bearer
      bearerFormat: bearer
security:
  - apiKey: []
tags:
  - name: traveler
    description: Travelers
  - name: trip
    description: Trips