openapi: "3.0.0"
info:
    version: "0.6.0"
    title: "Bremen calling API"
    description: Administer DEBRE ship calls, times and notifications
    termsOfService: "https://www.bsmd.de/" # url to terms page
    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:
    # tutorial: https://idratherbewriting.com/learnapidoc/pubapis_openapi_step3_servers_object.html
    - url: "https://brecaltest.bsmd-emswe.eu/"
      description: "Test server hosted on vcup"

paths:
    # tutorial: https://idratherbewriting.com/learnapidoc/pubapis_openapi_step4_paths_object.html
    /login:
        post:
            summary: Returns a JWT session token and user data if successful
            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:
            summary: Update user details (first/last name, phone, password)
            requestBody:
                description: User details
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/user_details"
            responses:
                400:
                    $ref: "#/components/responses/400"
                401:
                    $ref: "#/components/responses/401"
                500:
                    $ref: "#/components/responses/500"
                503:
                    $ref: "#/components/responses/503"

    /shipcalls:
        get:
            summary: Gets a list of ship calls
            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
            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
            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 registered shipcalls
            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 a particular participant entry corresponding to user id
            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"
                404:
                    $ref: "#/components/responses/404"
                401:
                    $ref: "#/components/responses/401"
                500:
                    $ref: "#/components/responses/500"
                503:
                    $ref: "#/components/responses/503"

    /times:
        get:
            summary: Get all recorded times for a a ship call
            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
            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
            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.
            parameters:
                - name: id
                  in: query
                  required: true
                  schema:
                      $ref: "#/components/schemas/timesId"
            responses:
                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
            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:
            summary: Gets a list of all berths registered
            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
            required:
                - username
                - password
            properties:
                username:
                    type: string
                password:
                    type: string
                    format: 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:
                    type: integer
                    # TODO: use an enum
                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:
                    type: integer
                    nullable: true
                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:
                    type: string
                    enum: [undefined, email, push]
                timestamp:
                    type: string
                    format: date-time
                acknowledged:
                    type: boolean
                created:
                    type: string
                    format: date-time
                modified:
                    type: string
                    format: date-time
                    nullable: true

        notification_list:
            type: array
            items:
                $ref: "#/components/schemas/notification"

        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
                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

    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: Invalid input
            content:
                application/json:
                    schema:
                        $ref: "#/components/schemas/Error"
        401:
            description: Not authorized
            content:
                application/json:
                    schema:
                        $ref: "#/components/schemas/Error"
        500:
            description: Unexpected error
            content:
                application/json:
                    schema:
                        $ref: "#/components/schemas/Error"
        503:
            description: Not available
            content:
                application/json:
                    schema:
                        $ref: "#/components/schemas/Error"

security:
    - ApiKey: []
externalDocs:
    url: http://textbausteine.net/
    description: Extra documentation and conditions for Bremen Calling