openapi: 3.0.0
info:
  title: Public API
  version: '1.0'
  description: This is the public API documentation, used by our iOS, Android and web apps.
servers:
  - url: 'http://api.mycompany.com/v1/'
paths:
  /books:
    post:
      summary: Book a trip
      tags: []
      responses:
        '200':
          description: Booked trip
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  trip_id:
                    type: string
                    format: uuid
                  cents:
                    type: string
                  status:
                    type: string
                    enum:
                      - booked
                      - canceled
                      - paid
      operationId: post-book
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                trip_id:
                  type: string
                voucher_code:
                  type: string
      description: Book a trip.
    parameters: []
  /search:
    post:
      summary: Search for a train trip
      tags: []
      responses:
        '200':
          description: An array of available trips.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    departure_station:
                      type: string
                    arrival_station:
                      type: string
                    departure_at:
                      type: string
                    arrival_at:
                      type: string
                    cents:
                      type: string
                    train_code:
                      type: string
              examples: {}
      operationId: post-search
      requestBody:
        content:
          application/json:
            examples:
                default:
                  summary: "Basic Origin-Destination search"
                  value:
                    departure_station: "Marseille"
                    destination_station: "Sisteron"
                    departure_around: "2023-05-04T09:42:00+00:00"
                via:
                  summary: "Search via a specific destination"
                  value:
                    departure_station: "Marseille"
                    via_station: "Valence"
                    destination_station: "Sisteron"
                    departure_around: "2023-05-04T09:42:00+00:00"
            schema:
              type: object
              required:
                - departure_station
                - destination_station
              properties:
                departure_station:
                  type: string
                via_station:
                  type: string
                destination_station:
                  type: string
                departure_around:
                  type: string
                  format: date-time
      description: 'Search for an available train trip between 2 stations, around a given departure date & time.'
  /payments:
    post:
      summary: Pay for a booked trip
      tags:
        - Payments
      responses:
        '200':
          description: Successful payment
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  book_id:
                    type: string
                  cents:
                    type: string
                  status:
                    type: string
                  '':
                    type: string
      operationId: post-charges
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                book_id:
                  type: string
                payment_token:
                  type: string
                  description: Payment token generated by the payment gateway.
                cents:
                  type: string
      description: ''
    parameters: []