dschick/git_brcal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
a5b16154c6
git_brcal/misc/BreCalApi.yaml
Daniel Schick a5b16154c6 Fixed saving of shipcall by correctly interpreting enums now 
The trick was to use a helper-field and a (decorated) @post_load method in the model that allows to fill the helper
fields with the values (ints) instead of strings for enums.
Trouble is: We are parsing strings from API/JSON and want to serialize as int (value in IntEnum). The helper
fields also must be skipped when setting up the query. Pretty convoluted, but gets the jon done (finally).

Also extended the database by new field 'interval_end' which is a preparation to allow not only timestamps but also
intervals when specifying times for participants.
2024-03-27 19:20:54 +01:00

1029 lines
28 KiB
YAML
Raw Blame History

openapi: 3.0.0
x-stoplight:
id: mwv4y8vcnopwr
info:
version: 1.2.0
title: Bremen calling API
description: 'Administer DEBRE ship calls, times and notifications'
termsOfService: 'https://www.bsmd.de/'
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:
- url: 'https://brecaldevel.bsmd-emswe.eu'
description: Development server hosted on vcup
tags:
- name: user
- name: shipcall
- name: times
- name: static
- name: ship
paths:
/login:
post:
description: Perform login
summary: Returns a JWT session token and user data if successful
tags:
- user
operationId: login
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:
description: Update user information
summary: 'Update user details (first/last name, phone, password)'
tags:
- user
operationId: userUpdate
requestBody:
description: User details
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/user_details'
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'
/shipcalls:
get:
description: Get current ship calls
summary: Gets a list of ship calls
tags:
- shipcall
operationId: shipcallsGet
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
description: A new shipcall is created without times at this point. This is ususally done by the BSMD or a participant with that particular role.
tags:
- shipcall
operationId: shipcallCreate
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
description: Updates a shipcall. Usually done if the participant assignments change.
tags:
- shipcall
operationId: shipcallUpdate
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 ships
description: Gets a list of ships including logically deleted ships to be used with shipcalls
tags:
- ship
operationId: shipsGet
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'
post:
summary: create a new ship entry
description: adds a new non-existing ship to the database. The ships IMO number is the unique identifier.
tags:
- ship
operationId: shipsCreate
requestBody:
description: Ship details. **Do not** provide id parameter.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ship'
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 ship entry
description: Updating a ship entry. Please do not modify the IMO number. In that case please add a new entry.
tags:
- ship
operationId: shipUpdate
requestBody:
description: Updated ship entry. The id parameter is **required**.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ship'
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 ship (logically).
description: 'A ship can only be logically deleted, since it is possible to have been used in previous shipcalls. On logical delete, the ship can no longer be selected in a new ship call.'
tags:
- ship
operationId: shipDelete
parameters:
- name: id
in: query
required: true
schema:
type: integer
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'
/participants:
get:
summary: gets one or all participants
description: 'If no parameter is given, all participants are returned. The list can be used to display participant information in the context of ship calls.'
tags:
- static
operationId: participantsGet
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'
'401':
$ref: '#/components/responses/401'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
'503':
$ref: '#/components/responses/503'
/times:
get:
summary: Gets list of times
description: Get all times assigned to a shipcall. These might not be complete.
tags:
- times
operationId: timesGet
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
description: The times entry for a shipcall is created with reference to a participant. For each participant type there should be only one times data record.
tags:
- times
operationId: timesCreate
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
description: Updating a times entry for a ship for a particular participant. The times entries are required for a shipcall to pass the validation rules.
tags:
- times
operationId: timesUpdate
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.
description: A times entry is typically deleted if the agent for example changes or removes the participant assignment for a particular role.
tags:
- times
operationId: timesDelete
parameters:
- name: id
in: query
required: true
schema:
$ref: '#/components/schemas/timesId'
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'
/notifications:
get:
summary: Gets a list of notifications pursuant to a specified participant and ship call
description: List of notifications (tbd)
tags:
- static
operationId: notificationsGet
parameters:
- 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:
description: 'Returns a list of berths, including berths that are (logically) deleted'
summary: Gets a list of all berths registered
tags:
- static
operationId: berthsGet
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'
/history:
get:
description: This endpoint returns a list of changes made to the specific shipcall
summary: History data
tags:
- static
operationId: historyGet
responses:
'200':
description: list of history entries
content:
application/json:
schema:
$ref: '#/components/schemas/history_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
properties:
username:
type: string
password:
type: string
format: password
required:
- username
- 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:
description: 'Currently this is encoded as an integer, since in OpenAPI 3.0 there are no enumerations supported with discrete integer values like a bitwise flag array used here. Each bit corresponds to a role. Since a participant can have multiple roles, these bits are combined by OR. Individual values: 1: BSMD 2: TERMINAL, 4: PILOT, 8: AGENCY, 16: MOORING, 32: PORT_ADMINISTRATION, 64: TUG'
type: integer
shipcall:
type: object
properties:
id:
$ref: '#/components/schemas/shipcallId'
ship_id:
type: integer
type:
$ref: '#/components/schemas/ShipcallType'
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: double
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:
$ref: '#/components/schemas/EvaluationType'
evaluation_message:
maxLength: 512
type: string
nullable: true
time_ref_point:
type: integer
nullable: true
description: Physical reference point for all times given in shipcall and depending times entries
participants:
type: array
items:
$ref: '#/components/schemas/participant_assignment'
created:
type: string
format: date-time
description: Readonly field set by the database
modified:
type: string
format: date-time
nullable: true
description: Readonly field set by the database
required:
- id
- ship_id
- type
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'
properties:
id:
type: integer
eta_berth:
type: string
format: date-time
nullable: true
description: Arrival time at berth
eta_berth_fixed:
type: boolean
nullable: true
description: currently unused
etd_berth:
type: string
format: date-time
nullable: true
description: departure time from berth
etd_berth_fixed:
type: boolean
nullable: true
description: currently unused
lock_time:
type: string
format: date-time
nullable: true
description: arrival time at lock
lock_time_fixed:
type: boolean
nullable: true
description: currently unused
zone_entry:
type: string
format: date-time
nullable: true
description: currently unused
zone_entry_fixed:
type: boolean
nullable: true
description: currently unused
operations_start:
type: string
format: date-time
nullable: true
description: Start time for terminal operations
operations_end:
type: string
format: date-time
nullable: true
description: End time for terminal operations
remarks:
type: string
maxLength: 512
nullable: true
shipcall_id:
type: integer
description: Reference to a shipcall id
participant_id:
type: integer
description: Reference to a participant id
berth_id:
type: integer
nullable: true
description: Reference to a berth id
berth_info:
type: string
nullable: true
maxLength: 512
description: Additional info text for berth
pier_side:
description: 'true if ship is rotated, false otherwise'
type: boolean
nullable: true
participant_type:
type: integer
ata_atd:
type: string
format: date-time
nullable: true
description: can be set by mooring if actual times are different from planned
interval_end:
type: string
format: date-time
nullable: true
description: End of the interval for the times entry
created:
type: string
format: date-time
description: Readonly field set by the database
modified:
type: string
format: date-time
nullable: true
description: Readonly field set by the database
required:
- shipcall_id
- participant_id
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
description: Optional reference to a participant (terminal)
authority_id:
type: integer
nullable: true
description: Optional reference to a participant (port authority)
lock:
type: boolean
nullable: true
description: If true lock must be passed
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
description: Optional reference to participant (tug role)
length:
type: number
format: double
nullable: true
width:
type: number
format: double
nullable: true
is_tug:
type: boolean
default: false
bollard_pull:
type: integer
nullable: true
eni:
type: integer
nullable: true
description: BSMD internal use
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'
history:
type: object
description: Single history entry with references
properties:
id:
type: integer
participant_id:
type: integer
shipcall_id:
type: integer
timestamp:
type: string
format: date-time
eta:
type: string
format: date-time
operation:
$ref: '#/components/schemas/OperationType'
type:
$ref: '#/components/schemas/ObjectType'
history_list:
type: array
items:
$ref: '#/components/schemas/history'
x-stoplight:
id: 93b5ff080c12a
notification:
type: object
description: a notification created by the engine if a times entry violates a rule
properties:
id:
type: integer
shipcall_id:
type: integer
notification_type:
$ref: '#/components/schemas/NotificationType'
message:
type: string
created:
type: string
format: date-time
description: Readonly field set by the database
modified:
type: string
format: date-time
nullable: true
description: Readonly field set by the database
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
description: a logical combination (bitflag) of possible values. This cannot be encoded in a Enumeration type with discrete values in OpenAPI version < 3.1. The values are 1=
flags:
type: integer
nullable: true
created:
type: string
format: date-time
description: Readonly field set by the database
modified:
type: string
format: date-time
nullable: true
description: Readonly field set by the database
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
maxLength: 128
new_password:
type: string
nullable: true
maxLength: 128
first_name:
type: string
nullable: true
maxLength: 45
last_name:
type: string
nullable: true
maxLength: 45
user_phone:
maxLength: 128
type: string
nullable: true
user_email:
maxLength: 128
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
ShipcallType:
type: string
enum:
- undefined
- arrival
- departure
- shifting
x-internal: false
description: ''
NotificationType:
type: string
enum:
- undefined
- email
- push
EvaluationType:
type: string
nullable: true
enum:
- undefined
- green
- yellow
- red
OperationType:
type: string
enum:
- undefined
- insert
- update
- delete
ObjectType:
type: string
enum:
- times
- shipcall
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: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Not authorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Service unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKey: []
externalDocs:
url: 'http://textbausteine.net/'
description: Extra documentation and conditions for Bremen Calling
x-internal: true
Reference in New Issue View Git Blame Copy Permalink