openapi: '3.0.0'
info:
  version: '1.0.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://puls200.dyn-dns.org:8088/brecal/api"
    description: "Test server self-hosted by yours truly"

paths:
  # tutorial: https://idratherbewriting.com/learnapidoc/pubapis_openapi_step4_paths_object.html    

  /shipcalls:
    get:
      summary: Gets a list of ship calls
      parameters:
        - name: participant_id          
          in: query
          required: true
          description: "**Id of participant**. *Example: 2*. Id of participant entity requesting ship calls"
          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:
        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:
        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'

  /participant:
    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 login call. No parameter returns all participants."
          schema:
            type: integer
      responses:
        200:
          description: ship call list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/participant'
        400:
          $ref: '#/components/responses/400'
        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:
        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:
        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:
    timesId:
      description: The unique identifier for a times entry
      type: integer
    shipcallId:
      description: The unique identifier of a ship call
      type: integer
    shipcall:
      type: object
      required:
        - id
        - ship_id
        - type      
        - eta
        - voyage
        - etd
      properties:
        id:
          $ref: '#/components/schemas/shipcallId'
        
        type:
          type: string
          enum:
            - incoming
            - outgoing
            - shifting          
            
        description:
          type: string

    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
        start_planned:
          type: string
          format: date-time
        end_planned:
          type: string
          format: date-time
        duration_planned:
          type: integer
        start_actual:
          type: string
          format: date-time
        end_actual:
          type: string
          format: date-time
        shipcall_id:
          type: integer
        participant_id:
          type: integer
      
    times_list:
      type: array
      items:
        $ref: '#/components/schemas/times'
      
    berth:
      type: object
      description: Ship berth used for a ship call
      properties:
        id:
          type: integer
        name1:
          type: string
        name2:
          type: string

    berth_list:
      type: array
      items:
        $ref: '#/components/schemas/berth'

    ship:
      type: object
      description: a ship
      properties:
        id:
          type: integer
        name:
          type: string
        imo:
          type: integer
        callsign:
          type: string
        length:
          type: number
          format: float          
        width:
          type: number
          format: float
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time

    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
      
    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
        street:
          type: string
        postal code:
          type: string
        city: 
          type: string

    Error:
      type: object
      required:
        - message
      properties:
        message:
          description: A human readable error message
          type: string

  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
  responses:
    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