openapi: 3.1.0
x-stoplight:
  id: iucm9tq7jgu7j
info:
  version: 1.1.0
  title: Bremen calling API
  description: 'Administer DEBRE ship calls, times and notifications'
  termsOfService: 'https://www.bsmd.de/'
  contact:
    name: Bremen calling API
    url: 'https://www.textbausteine.net'
    email: info@textbausteine.net
  license:
    name: Use at your own risk
    url: 'https://www.bsmd.de/license'
  summary: Bremen calling
servers:
  - url: 'https://brecaldevel.bsmd-emswe.eu'
    description: Development server hosted on vcup
tags:
  - name: user
  - name: shipcall
  - name: times
  - name: static
paths:
  /login:
    post:
      description: Perform login
      summary: Returns a JWT session token and user data if successful
      tags:
        - user
      operationId: login
      requestBody:
        description: Login credentials
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/credentials'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/login_result'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /user:
    put:
      description: Update user information
      summary: 'Update user details (first/last name, phone, password)'
      tags:
        - user
      operationId: userUpdate
      requestBody:
        description: User details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/user_details'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /shipcalls:
    get:
      description: Get current ship calls
      summary: Gets a list of ship calls
      tags:
        - shipcall
      operationId: shipcallsGet
      parameters:
        - name: past_days
          in: query
          required: false
          description: 'number of days in the past to include in the result. *Example: 7*.'
          schema:
            type: integer
      responses:
        '200':
          description: ship call list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipcalls'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
    post:
      summary: Create a new ship call
      description: A new shipcall is created without times at this point. This is ususally done by the BSMD or a participant with that particular role.
      tags:
        - shipcall
      operationId: shipcallCreate
      requestBody:
        description: Creates a new ship call. **Do not** provide id parameter.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shipcall'
      responses:
        '201':
          $ref: '#/components/responses/201'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
    put:
      summary: Updates a ship call
      description: Updates a shipcall. Usually done if the participant assignments change.
      tags:
        - shipcall
      operationId: shipcallUpdate
      requestBody:
        description: Creates a new ship call. The id parameter is **required**.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shipcall'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /ships:
    get:
      summary: gets a list of ships
      description: Gets a list of ships including logically deleted ships to be used with shipcalls
      tags:
        - static
      operationId: shipsGet
      responses:
        '200':
          description: list of ships
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ship_list'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /participants:
    get:
      summary: gets one or all participants
      description: 'If no parameter is given, all participants are returned. The list can be used to display participant information in the context of ship calls.'
      tags:
        - static
      operationId: participantsGet
      parameters:
        - name: user_id
          in: query
          required: false
          description: '**Id of user**. *Example: 2*. User id returned by verify call.'
          schema:
            type: integer
      responses:
        '200':
          description: ship call list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/participant_list'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /times:
    get:
      summary: Gets list of times
      description: Get all times assigned to a shipcall. These might not be complete.
      tags:
        - times
      operationId: timesGet
      parameters:
        - name: shipcall_id
          in: query
          description: '**Id**. *Example: 42*. Id of referenced ship call.'
          schema:
            type: integer
      responses:
        '200':
          description: list of recorded times
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/times_list'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
    post:
      summary: Create a new times entry for a ship call
      description: The times entry for a shipcall is created with reference to a participant. For each participant type there should be only one times data record.
      tags:
        - times
      operationId: timesCreate
      requestBody:
        description: Times entry that will be added to the ship call. **Do not** provide id parameter.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/times'
      responses:
        '201':
          $ref: '#/components/responses/201'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
    put:
      summary: Update a times entry for a ship call
      description: Updating a times entry for a ship for a particular participant. The times entries are required for a shipcall to pass the validation rules.
      tags:
        - times
      operationId: timesUpdate
      requestBody:
        description: Times entry that will be added to the ship call. The id parameter is **required**.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/times'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
    delete:
      summary: Delete a times entry for a ship call.
      description: A times entry is typically deleted if the agent for example changes or removes the participant assignment for a particular role.
      tags:
        - times
      operationId: timesDelete
      parameters:
        - name: id
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/timesId'
      responses:
        '200':
          $ref: '#/components/responses/200'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /notifications:
    get:
      summary: Gets a list of notifications pursuant to a specified participant and ship call
      description: List of notifications (tbd)
      tags:
        - static
      operationId: notificationsGet
      parameters:
        - name: participant_id
          in: query
          required: true
          description: '**Id of participant**. *Example: 2*. Id returned through loading of participant'
          schema:
            type: integer
        - name: shipcall_id
          in: query
          required: true
          description: '**Id of ship call**. *Example: 52*. Id given in ship call list'
          schema:
            $ref: '#/components/schemas/shipcallId'
      responses:
        '200':
          description: notification list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notification'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /berths:
    get:
      description: 'Returns a list of berths, including berths that are (logically) deleted'
      summary: Gets a list of all berths registered
      tags:
        - static
      operationId: berthsGet
      responses:
        '200':
          description: list of berths
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/berth_list'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
components:
  schemas:
    credentials:
      type: object
      properties:
        username:
          type: string
        password:
          type: string
          format: password
      required:
        - username
        - password
    timesId:
      description: The unique identifier for a times entry
      type: integer
    shipcallId:
      description: The unique identifier of a ship call
      type: integer
    participant_assignment:
      description: Participant assigned to a shipcall with a given role (type)
      type: object
      required:
        - participant_id
        - type
      properties:
        participant_id:
          type: integer
        type:
          type: integer
    shipcall:
      type: object
      required:
        - id
        - ship_id
        - type
      properties:
        id:
          $ref: '#/components/schemas/shipcallId'
        ship_id:
          type: integer
        type:
          $ref: '#/components/schemas/ShipcallType'
        eta:
          type: string
          format: date-time
          nullable: true
        voyage:
          type: string
          maxLength: 16
          nullable: true
        etd:
          type: string
          format: date-time
          nullable: true
        arrival_berth_id:
          type: integer
          nullable: true
        departure_berth_id:
          type: integer
          nullable: true
        tug_required:
          type: boolean
          nullable: true
        pilot_required:
          type: boolean
          nullable: true
        flags:
          type: integer
          nullable: true
        pier_side:
          type: boolean
          nullable: true
        bunkering:
          type: boolean
          nullable: true
        replenishing_terminal:
          type: boolean
          nullable: true
        replenishing_lock:
          type: boolean
          nullable: true
        draft:
          type: number
          format: float
          nullable: true
        tidal_window_from:
          type: string
          format: date-time
          nullable: true
        tidal_window_to:
          type: string
          format: date-time
          nullable: true
        rain_sensitive_cargo:
          type: boolean
          nullable: true
        recommended_tugs:
          type: integer
          nullable: true
        anchored:
          type: boolean
          nullable: true
        moored_lock:
          type: boolean
          nullable: true
        canceled:
          type: boolean
          nullable: true
        evaluation:
          type: integer
          nullable: true
        evaluation_message:
          type: string
          nullable: true
        participants:
          type: array
          items:
            $ref: '#/components/schemas/participant_assignment'
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
          nullable: true
    shipcalls:
      type: array
      items:
        $ref: '#/components/schemas/shipcall'
    times:
      type: object
      description: 'the id parameter needs to be missing on POST and to be present on PUT (Update) calls, otherwise a 400 response will be generated'
      required:
        - shipcall_id
        - participant_id
      properties:
        id:
          type: integer
        eta_berth:
          type: string
          format: date-time
          nullable: true
        eta_berth_fixed:
          type: boolean
          nullable: true
        etd_berth:
          type: string
          format: date-time
          nullable: true
        etd_berth_fixed:
          type: boolean
          nullable: true
        lock_time:
          type: string
          format: date-time
          nullable: true
        lock_time_fixed:
          type: boolean
          nullable: true
        zone_entry:
          type: string
          format: date-time
          nullable: true
        zone_entry_fixed:
          type: boolean
          nullable: true
        operations_start:
          type: string
          format: date-time
          nullable: true
        operations_end:
          type: string
          format: date-time
          nullable: true
        remarks:
          type: string
          maxLength: 512
          nullable: true
        shipcall_id:
          type: integer
        participant_id:
          type: integer
        berth_id:
          type: integer
          nullable: true
        berth_info:
          type: string
          nullable: true
        pier_side:
          type: boolean
          nullable: true
        participant_type:
          $ref: '#/components/schemas/ParticipantType2'
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
          nullable: true
    times_list:
      type: array
      items:
        $ref: '#/components/schemas/times'
    berth:
      type: object
      description: Ship berth used for a ship call
      properties:
        id:
          type: integer
        name:
          type: string
          maxLength: 128
        owner_id:
          type: integer
          nullable: true
        authority_id:
          type: integer
          nullable: true
        lock:
          type: boolean
          nullable: true
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
          nullable: true
        deleted:
          type: boolean
          default: false
    berth_list:
      type: array
      items:
        $ref: '#/components/schemas/berth'
    ship:
      type: object
      description: a ship
      properties:
        id:
          type: integer
        name:
          type: string
          maxLength: 64
        imo:
          type: integer
          nullable: true
        callsign:
          type: string
          maxLength: 8
          nullable: true
        participant_id:
          type: integer
          nullable: true
        length:
          type: number
          format: float
          nullable: true
        width:
          type: number
          format: float
          nullable: true
        is_tug:
          type: boolean
          default: false
        bollard_pull:
          type: integer
          nullable: true
        eni:
          type: integer
          nullable: true
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
          nullable: true
        deleted:
          type: boolean
          default: false
    ship_list:
      type: array
      items:
        $ref: '#/components/schemas/ship'
    notification:
      type: object
      description: a notification created by the engine if a times entry violates a rule
      properties:
        id:
          type: integer
        times_id:
          type: integer
        participant_id:
          type: integer
        notification_type:
          $ref: '#/components/schemas/NotificationType'
        timestamp:
          type: string
          format: date-time
        acknowledged:
          type: boolean
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
          nullable: true
    participant:
      type: object
      description: A organisational entity that participates in Bremen Calling
      properties:
        id:
          type: integer
        name:
          type: string
          maxLength: 128
        street:
          type: string
          maxLength: 128
        postal code:
          type: string
          maxLength: 5
        city:
          type: string
          maxLength: 64
        type:
          type: integer
          description: a logical combinat
        flags:
          type: integer
          nullable: true
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
          nullable: true
        deleted:
          type: boolean
          default: false
    participant_list:
      type: array
      items:
        $ref: '#/components/schemas/participant'
    login_result:
      type: object
      description: result structure of a successful login attempt
      properties:
        id:
          type: integer
        participant_id:
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        user_name:
          type: string
        user_phone:
          type: string
        user_email:
          type: string
        exp:
          type: number
          format: float
        token:
          type: string
    user_details:
      type: object
      description: fields that a user may change
      properties:
        id:
          type: integer
        old_password:
          type: string
          nullable: true
        new_password:
          type: string
          nullable: true
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        user_phone:
          type: string
          nullable: true
        user_email:
          type: string
          nullable: true
    Id:
      type: object
      description: A unique identifier for an entity
      properties:
        id:
          type: integer
    Error:
      type: object
      required:
        - message
      properties:
        message:
          description: A human readable error message
          type: string
    ShipcallType:
      type: string
      enum:
        - undefined
        - arrival
        - departure
        - shifting
      x-internal: false
      description: ''
    NotificationType:
      type: string
      enum:
        - undefined
        - email
        - push
    ParticipantType:
      type: integer
      enum:
        - 1
        - 2
        - 4
        - 8
        - 16
        - 32
        - 64
      x-enumDescriptions:
        '1': bsmd
        '2': terminal
        '4': pilot
        '8': agency
        '16': mooring
        '32': port_authority
        '64': tug
    ParticipantType2:
      title: ParticipantType2
      x-stoplight:
        id: whw0m8x8dq6cg
      type: integer
      oneOf:
        - const: 1
          title: bsmd
          description: Bremen Schiffsmeldedienst
        - const: 2
          title: terminal
          description: Terminal
        - const: 4
          title: pilot
          description: Pilot
        - const: 8
          title: agency
          description: Agency
        - const: 16
          title: mooring
          description: Mooring
        - const: 32
          title: port_authority
          description: Port Authority
        - const: 64
          title: tug
          description: Tug
      description: Enumeration that can take particular values
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization
  responses:
    '200':
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Id'
    '201':
      description: Created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Id'
    '400':
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Not authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '503':
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
security:
  - ApiKey: []
externalDocs:
  url: 'http://textbausteine.net/'
  description: Extra documentation and conditions for Bremen Calling
x-internal: true