776 lines
25 KiB
YAML
776 lines
25 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:
|
|
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
|
|
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
|
|
evaluation:
|
|
type: integer
|
|
nullable: true
|
|
evaluation_message:
|
|
type: string
|
|
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
|
|
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
|