puls200
110ff5ccce
Participants can be of multiple types (e.g. agent and terminal), therefore the participant type must be stored in the times data record in order to assign times correctly during display and to differentiate in calculation.
745 lines
24 KiB
YAML
745 lines
24 KiB
YAML
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: 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"
|
|
|
|
/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:
|
|
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:
|
|
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
|
|
shipcall:
|
|
type: object
|
|
required:
|
|
- id
|
|
- ship_id
|
|
- type
|
|
- eta
|
|
properties:
|
|
id:
|
|
$ref: "#/components/schemas/shipcallId"
|
|
ship_id:
|
|
type: integer
|
|
type:
|
|
type: integer
|
|
# TODO: use an enum
|
|
eta:
|
|
type: string
|
|
format: date-time
|
|
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
|
|
participants:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
example: [1, 5, 7]
|
|
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
|
|
participant_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
|
|
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
|
|
|
|
Error:
|
|
type: object
|
|
required:
|
|
- message
|
|
properties:
|
|
message:
|
|
description: A human readable error message
|
|
type: string
|
|
|
|
securitySchemes:
|
|
ApiKey:
|
|
type: apiKey
|
|
in: header
|
|
name: Authorization
|
|
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
|