openapi: 3.0.0
x-stoplight:
  id: mwv4y8vcnopwr
info:
  version: 1.2.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'
servers:
  - url: 'https://brecal.bsmd-emswe.eu'
    description: Development server hosted on vcup
tags:
  - name: user
  - name: shipcall
  - name: times
  - name: static
  - name: ship
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:
        - ship
      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'
    post:
      summary: create a new ship entry
      description: adds a new non-existing ship to the database. The ships IMO number is the unique identifier.
      tags:
        - ship
      operationId: shipsCreate
      requestBody:
        description: Ship details. **Do not** provide id parameter.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ship'
      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 ship entry
      description: Updating a ship entry. Please do not modify the IMO number. In that case please add a new entry.
      tags:
        - ship
      operationId: shipUpdate
      requestBody:
        description: Updated ship entry. The id parameter is **required**.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ship'
      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 ship (logically).
      description: 'A ship can only be logically deleted, since it is possible to have been used in previous shipcalls. On logical delete, the ship can no longer be selected in a new ship call.'
      tags:
        - ship
      operationId: shipDelete
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: integer
      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'
  /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: 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'
  /history:
    get:
      description: This endpoint returns a list of changes made to the specific shipcall
      summary: History data
      tags:
        - static
      operationId: historyGet
      parameters:
        - 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: list of history entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/history_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:
          description: 'Currently this is encoded as an integer, since in OpenAPI 3.0 there are no enumerations supported with discrete integer values like a bitwise flag array used here. Each bit corresponds to a role. Since a participant can have multiple roles, these bits are combined by OR. Individual values: 1: BSMD 2: TERMINAL, 4: PILOT, 8: AGENCY, 16: MOORING, 32: PORT_ADMINISTRATION, 64: TUG'
          type: integer
    shipcall:
      type: object
      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: double
          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:
          $ref: '#/components/schemas/EvaluationType'
        evaluation_message:
          maxLength: 512
          type: string
          nullable: true
        time_ref_point:
          type: integer
          nullable: true
          description: Physical reference point for all times given in shipcall and depending times entries
        participants:
          type: array
          items:
            $ref: '#/components/schemas/participant_assignment'
        created:
          type: string
          format: date-time
          description: Readonly field set by the database
        modified:
          type: string
          format: date-time
          nullable: true
          description: Readonly field set by the database
      required:
        - id
        - ship_id
        - type
    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'
      properties:
        id:
          type: integer
        eta_berth:
          type: string
          format: date-time
          nullable: true
          description: Arrival time at berth
        eta_berth_fixed:
          type: boolean
          nullable: true
          description: currently unused
        etd_berth:
          type: string
          format: date-time
          nullable: true
          description: departure time from berth
        etd_berth_fixed:
          type: boolean
          nullable: true
          description: currently unused
        lock_time:
          type: string
          format: date-time
          nullable: true
          description: arrival time at lock
        lock_time_fixed:
          type: boolean
          nullable: true
          description: currently unused
        zone_entry:
          type: string
          format: date-time
          nullable: true
          description: currently unused
        zone_entry_fixed:
          type: boolean
          nullable: true
          description: currently unused
        operations_start:
          type: string
          format: date-time
          nullable: true
          description: Start time for terminal operations
        operations_end:
          type: string
          format: date-time
          nullable: true
          description: End time for terminal operations
        remarks:
          type: string
          maxLength: 512
          nullable: true
        shipcall_id:
          type: integer
          description: Reference to a shipcall id
        participant_id:
          type: integer
          description: Reference to a participant id
        berth_id:
          type: integer
          nullable: true
          description: Reference to a berth id
        berth_info:
          type: string
          nullable: true
          maxLength: 512
          description: Additional info text for berth
        pier_side:
          description: 'true if ship is rotated, false otherwise'
          type: boolean
          nullable: true
        participant_type:
          type: integer
        ata:
          type: string
          format: date-time
          nullable: true
          description: can be set by mooring if actual times are different from planned
        atd:
          type: string
          format: date-time
          nullable: true
          description: can be set by mooring if actual times are different from planned
        eta_interval_end:
          type: string
          format: date-time
          nullable: true
          description: Optional end of the interval for the times eta entry
        etd_interval_end:
          type: string
          format: date-time
          nullable: true
          description: Optional end of the interval for the times etd entry
        created:
          type: string
          format: date-time
          description: Readonly field set by the database
        modified:
          type: string
          format: date-time
          nullable: true
          description: Readonly field set by the database
      required:
        - shipcall_id
        - participant_id
    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
          description: Optional reference to a participant (terminal)
        authority_id:
          type: integer
          nullable: true
          description: Optional reference to a participant (port authority)
        lock:
          type: boolean
          nullable: true
          description: If true lock must be passed
        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
          description: Optional reference to participant (tug role)
        length:
          type: number
          format: double
          nullable: true
        width:
          type: number
          format: double
          nullable: true
        is_tug:
          type: boolean
          default: false
        bollard_pull:
          type: integer
          nullable: true
        eni:
          type: integer
          nullable: true
          description: BSMD internal use
        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'
    history:
      type: object
      description: Single history entry with references
      properties:
        id:
          type: integer
        participant_id:
          type: integer
        shipcall_id:
          type: integer
        timestamp:
          type: string
          format: date-time
        eta:
          type: string
          format: date-time
        operation:
          $ref: '#/components/schemas/OperationType'
        type:
          $ref: '#/components/schemas/ObjectType'
    history_list:
      type: array
      items:
        $ref: '#/components/schemas/history'
      x-stoplight:
        id: 93b5ff080c12a
    notification:
      type: object
      description: a notification created by the engine if a times entry violates a rule
      properties:
        id:
          type: integer
        shipcall_id:
          type: integer
        notification_type:
          $ref: '#/components/schemas/NotificationType'
        message:
          type: string
        created:
          type: string
          format: date-time
          description: Readonly field set by the database
        modified:
          type: string
          format: date-time
          nullable: true
          description: Readonly field set by the database
    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 combination (bitflag) of possible values. This cannot be encoded in a Enumeration type with discrete values in OpenAPI version < 3.1. The values are 1=
        flags:
          type: integer
          nullable: true
        created:
          type: string
          format: date-time
          description: Readonly field set by the database
        modified:
          type: string
          format: date-time
          nullable: true
          description: Readonly field set by the database
        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
          maxLength: 128
        new_password:
          type: string
          nullable: true
          maxLength: 128
        first_name:
          type: string
          nullable: true
          maxLength: 45
        last_name:
          type: string
          nullable: true
          maxLength: 45
        user_phone:
          maxLength: 128
          type: string
          nullable: true
        user_email:
          maxLength: 128
          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
    EvaluationType:
      type: string
      nullable: true
      enum:
        - undefined
        - green
        - yellow
        - red
    OperationType:
      type: string
      enum:
        - undefined
        - insert
        - update
        - delete
    ObjectType:
      type: string
      enum:
        - times
        - shipcall
  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