openapi: 3.0.3
info:
  title: travelynx
  version: 0.1.0
  description: Travelynx API
servers:
  - url: 'https://travelynx.de/api/v1'
  - url: 'https://travellynx.de/api/v1'
  - url: 'https://travelynx.finalrewind.org/api/v1'
tags:
  - name: Status
    description: 'Query check-in and journey status'
  - name: Travel
    description: 'Check into and out of trains'
  - name: Import
    description: 'Import a journey'
paths:
  '/status/{token}':
    get:
      tags:
        - Status
      summary: Retrieves a user's status
      parameters:
        - in: path
          name: token
          schema:
            $ref: '#/components/schemas/token'
          required: true
          description: Status Token
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/status'
  '/travel':
    post:
      tags:
        - Travel
      summary: Check into or out of a train
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/checkinRequest'
              - $ref: '#/components/schemas/checkoutRequest'
              - $ref: '#/components/schemas/undoRequest'
            examples:
              checkin:
                value: {"action": "checkin", "token": "FIXME"}
              checkout:
                value: {"action": "checkout", "token": "FIXME"}
              undo:
                value: {"action": "undo", "token": "FIXME"}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/travelResponse'
components:
  schemas:
    token:
      type: string
      description: Status Token as configured on Travelynx User Panel
    status:
      type: object
      properties:
        deprecated:
          type: boolean
          example: false
          description: if true, this API version is no longer supported and will be removed in the future
        checkedIn:
          type: boolean
          example: true
          description: Is the user currently checked into a train?
        fromStation:
          $ref: '#/components/schemas/departureStatus'
        toStation:
          $ref: '#/components/schemas/arrivalStatus'
        intermediateStops:
          type: array
          items:
            $ref: '#/components/schemas/intermediateStop'
        train:
          $ref: '#/components/schemas/train'
        actionTime:
          type: number
          example: 1556083434
          description: checkin/checkout epoch
    travelRequest:
      type: object
      discriminator:
        propertyName: action
        mapping:
          checkin: checkinRequest
          checkout: checkoutRequest
          undo: undoRequest
      properties:
        token:
          type: string
        action:
          type: string
          enum: ['checkin', 'checkout', 'undo']
      required:
        - token
        - action
    checkinRequest:
      allOf:
      - $ref: '#/components/schemas/travelRequest'
      - type: object
        properties:
          train:
            type: object
            properties:
              type:
                type: string
                example: "ICE"
              no:
                type: string
                example: "209"
          fromStation:
            $ref: '#/components/schemas/station'
          toStation:
            $ref: '#/components/schemas/station'
          comment:
            type: string
        required: ['train', 'fromStation']
    checkoutRequest:
      allOf:
        - $ref: '#/components/schemas/travelRequest'
        - type: object
          properties:
            force:
              type: boolean
              description: "If true: perform checkout now. May lead to log entries without arrival time"
              default: false
            toStation:
              $ref: '#/components/schemas/station'
            comment:
              type: string
          required: ['toStation']
    undoRequest:
      allOf:
      - $ref: '#/components/schemas/travelRequest'
      - type: object
    travelResponse:
      type: object
      properties:
        deprecated:
          type: boolean
          example: false
          description: if true, this API version is no longer supported and will be removed in the future
        success:
          type: boolean
          example: true
        status:
          $ref: '#/components/schemas/status'
    departureStatus:
      type: object
      properties:
        name:
          type: string
          example: "Essen Hbf"
        ds100:
          type: string
          example: "EE"
        uic:
          type: number
          example: 8000098
        latitude:
          type: number
          example: 51.451355
        longitude:
          type: number
          example: 7.014793
        scheduledTime:
          type: number
          example: 1556083680
        realtime:
          type: number
          example: 1556083680
    arrivalStatus:
      type: object
      description: If journey destination is not yet known, all fields are null
      nullable: true
      properties:
        name:
          type: string
          example: "Essen Stadtwald"
        ds100:
          type: string
          example: "EESA"
        uic:
          type: number
          example: 8001896
        latitude:
          type: number
          example: 51.422853
        longitude:
          type: number
          example: 7.023296
        scheduledTime:
          type: number
          example: 1556083980
          nullable: true
          description: If arrival time is not yet known, this field is null
        realtime:
          type: number
          example: 1556083980
          nullable: true
          description: If arrival time is not yet known, this field is null
    intermediateStop:
      type: object
      properties:
        name:
          type: string
          example: "Essen Süd"
        scheduledArrival:
          type: number
          example: 1556083800
          nullable: true
        realArrival:
          type: number
          example: 1556083800
          nullable: true
        scheduledDeparture:
          type: number
          example: 1556083860
          nullable: true
        realDeparture:
          type: number
          example: 1556083860
          nullable: true
    train:
      type: object
      properties:
        type:
          type: string
          example: "S"
        line:
          type: string
          example: "6"
        no:
          type: string
          example: "30634"
        id:
          type: string
          example: "7512500863736016593"
          description: IRIS-specific train ID
    station:
      oneOf:
      - type: string
        description: Station Name
        example: "Essen Hbf"
      - type: string
        description: DS100 Code
        example: "EE"
      - type: number
        description: EVA number
        example: 8000098