openapi: "3.0.0"
info:
  title: "Ports and Vessels Api"
  version: "1.0.1"
  description: Welcome to the documentation of the Ports and Vessels  API
    
    <h1>Compatibility guidelines</h1>
    <p>The HTTP API is versioned with a single number, which is currently 1</p>
    <p>This number symbolizes the major version number. New features can be added to the API in the same version number if there is no breaking change.</p>
    <p>The version number is present in the url, for instance <strong>/ports-vessels/api/v1</strong> for the current version.
    
    <h1>Documentation, Pricing and Key generation</h1>
    <p>You can find the complete documentation for our API at <a href='https://developers.sinay.ai/'>Developers Platform</a>.</p>
    <p>Create an account to receive your FREE key in under a minute!</p>
    <p>Additionally, explore our pricing plans, access support, view detailed documentation, and follow our comprehensive tutorials.</p>
    
    <h1>Authentication</h1>
    <p>Every endpoints of this API require authentication using an API key.</p>
    <p>If you don't have an API Key and you need to use the Ports and Vessels  API, you need to ask Sinay to have one.</p>
    <p>To use the API Key, you must add a header named <strong>API_KEY</strong> with your API Key as a value.</p>
    <h1>Test the API with Swagger-ui</h1>
    <p>To test the API using Swagger-ui, you must click on the button <strong>Authorize</strong> and then fill the <strong>apiKey</strong> field and click on <strong>Authorize</strong>.</p>
    <p>Swagger-ui will then use the api key automatically in each request.</p>
    <p>On every endpoints, you can click on <strong>Try it out</strong>, you can modify the body
    and then click on <strong>Execute</strong></p>
    <p>You will be able to see the response.</p>
    
    <h1>Release note</h1>
    <h2>1.0.0</h2>
    <ul>
    <li>Retrieve possible vessels</li>
    <li>Retrieve possible ports</li>
    </ul>
servers:
  - url: "https://api.sinay.ai/ports-vessels/api/v1"
tags:
  - name: ports
    description: Endpoints that allows you to retrieve a list of ports that can match your input
  - name: vessels
    description: Endpoints that allows you to retrieve a list of vessels that can match your input
paths:
  "/ports":
    get:
      parameters:
        - $ref: '#/components/parameters/portNameOrCode'
        - $ref: '#/components/parameters/numberOfResult'
      operationId: "getPortsByNameOrCode"
      summary: Retrieve a list of ports from a name or an unlocode.
      tags:
        - ports
      description:
        <p>This endpoint is used to retrieve a list of ports that can match your input.</p>
        <p>It will return a list of of none/one/several ports depending of the result of the search.</p>
        <p>If there is no port that match your input the ports list will be empty.</p>
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/portsResponse"
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/errorInfo"
        '500':
          $ref: '#/components/responses/internalServerError'

  "/vessels":
    get:
      parameters:
        - $ref: '#/components/parameters/vesselNameOrCode'
        - $ref: '#/components/parameters/numberOfResult'
      operationId: "getVesselsByName"
      summary: Retrieve a list of vessels from a name, a MMSI or an IMO.
      tags:
        - vessels
      description:
        <p>This endpoint is used to retrieve a list of vessels that can match your input.</p>
        <p>It will return a list of of none/one/several vessels depending of the result of the search.</p>
        <p>If there is no vessel that match your input the vessels list will be empty.</p>
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/vesselsResponse"
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/errorInfo"
        '500':
          $ref: '#/components/responses/internalServerError'

  "/usages":
    get:
      parameters:
        - $ref: '#/components/parameters/usageStartTime'
        - $ref: '#/components/parameters/usageEndTime'
      operationId: "retrieveUsages"
      summary: "Retrieve your monthly usages"
      description:
        <p>The endpoint allows you to retrieve your monthly usages of the API</p>
      tags:
        - Usage
      responses:
        '200':
          description: "The monthly usages"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/usagesResponse'
        '401':
          $ref: '#/components/responses/unauthorized'
        '500':
          $ref: '#/components/responses/internalServerError'
        default:
          $ref: '#/components/responses/default'

components:
  schemas:
    portsResponse:
      type: object
      properties:
        input:
          type: string
          example : bal
        portsList:
          $ref: "#/components/schemas/ports"
    ports:
      type: array
      items:
        $ref: "#/components/schemas/port"
    port:
      type: object
      properties:
        unlocode:
          type: string
          example: USBAL
        name:
          type: string
          example: BALTIMORE

    vesselsResponse:
      type: object
      properties:
        input:
          type: string
          example : cla
        vesselsList:
          $ref: "#/components/schemas/vessels"

    vessels:
      type: array
      items:
        $ref: "#/components/schemas/vessel"
    vessel:
      type: object
      properties:
        name:
          type: string
          example: SANTA CLARA
        imo:
          type: string
          example: 9444716
        mmsi:
          type: string
          example: 219075000

    usagesResponse:
      type: object
      required:
        - allCalls
        - successCalls
        - clientErrorCalls
        - serverErrorCalls
        - consumedApiUnits
      properties:
        allCalls:
          $ref: '#/components/schemas/numberOfCalls'
        successCalls:
          $ref: '#/components/schemas/numberOfCalls'
        clientErrorCalls:
          $ref: '#/components/schemas/numberOfCalls'
        serverErrorCalls:
          $ref: '#/components/schemas/numberOfCalls'
        consumedApiUnits:
          $ref: '#/components/schemas/numberOfCalls'
        periodicUsages:
          $ref: '#/components/schemas/periodicUsages'
      example:
        allCalls: 15
        successCalls: 13
        clientErrorCalls: 1
        serverErrorCalls: 1
        consumedApiUnits: 25
        periodicUsages:
          2022-05:
            allCalls: 15
            successCalls: 13
            clientErrorCalls: 1
            serverErrorCalls: 1
            consumedApiUnits: 25
    periodicUsages:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/periodicUsage'
    periodicUsage:
      type: object
      required:
        - allCalls
        - successCalls
        - clientErrorCalls
        - serverErrorCalls
        - consumedApiUnits
      properties:
        allCalls:
          $ref: '#/components/schemas/numberOfCalls'
        successCalls:
          $ref: '#/components/schemas/numberOfCalls'
        clientErrorCalls:
          $ref: '#/components/schemas/numberOfCalls'
        serverErrorCalls:
          $ref: '#/components/schemas/numberOfCalls'
        consumedApiUnits:
          $ref: '#/components/schemas/numberOfCalls'
    numberOfCalls:
      type: integer
      format: int64

    errorInfo:
      type: object
      required:
        - errorCode
        - message
        - details
        - time
      properties:
        errorCode:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            type: string
        time:
          type: string
          format: date-time

  parameters:
    portNameOrCode:
      in: query
      name: portNameOrCode
      required: true
      schema:
        type: string
        pattern: "[a-zA-Z0-9\\s]{3,}"
        minLength: 3
      description: Please enter at least 3 letters of the port name or the port code.
      example : bal
    vesselNameOrCode:
      in: query
      name: vesselNameOrCode
      required: true
      schema:
        type: string
        pattern: "[a-zA-Z0-9\\s]{3,}"
        minLength: 3
      description: Please enter at least 3 letters of the vessel name, the MMSI or the IMO.
      example : cla

    numberOfResult:
      in: query
      name: numberOfResult
      schema:
        type: integer
        default: 10
        minimum: 10
        maximum: 100
      description: Number of results per request. Default is 10, minimum is 10, maximum is 100.
      example : 10


    usageStartTime:
      in: query
      name: startTime
      required: false
      schema:
        type: string
        format: date-time
      description: Start time at which usages must be found
    usageEndTime:
      in: query
      name: endTime
      required: false
      schema:
        type: string
        format: date-time
      description: End time at which usages must be found
  responses:
    badRequest:
      description: The body in the request is not correct
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    internalServerError:
      description: An error occurend on server side
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    notFound:
      description: The resource has not been found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    conflict:
      description: The resource already exists
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    unauthorized:
      description: The authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
    default:
      description: default
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorInfo'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: API_KEY
security:
  - ApiKey: [ ]