Added a documentation file for the API spec
This commit is contained in:
parent
b5dd7422f4
commit
9116841292
526
misc/BreCalApi.md
Normal file
526
misc/BreCalApi.md
Normal file
@ -0,0 +1,526 @@
|
||||
# Bremen calling API
|
||||
_Version 1.7.0_
|
||||
|
||||
Administer DEBRE ship calls, times and notifications
|
||||
|
||||
## Authentication
|
||||
- **ApiKey**: API key in `header` header named `Authorization`.
|
||||
|
||||
## Ship Endpoints
|
||||
|
||||
### `DELETE /ships`
|
||||
**Summary:** Delete a ship (logically).
|
||||
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.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Type | Required | Description |
|
||||
|------|----|------|----------|-------------|
|
||||
| id | query | integer | Yes | **Id of ship**. *Example: 42*. Id of ship to be deleted. |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
### `GET /ships`
|
||||
**Summary:** gets a list of ships
|
||||
Gets a list of ships including logically deleted ships to be used with shipcalls
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**: list of ships
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
### `POST /ships`
|
||||
**Summary:** create a new ship entry
|
||||
adds a new non-existing ship to the database. The ships IMO number is the unique identifier.
|
||||
|
||||
#### Request Body
|
||||
Ship details. **Do not** provide id parameter.
|
||||
|
||||
**JSON Schema**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| id | integer | No | |
|
||||
| name | string | No | |
|
||||
| imo | integer | No | |
|
||||
| callsign | string | No | |
|
||||
| participant_id | integer | No | Optional reference to participant (tug role) |
|
||||
| length | number | No | |
|
||||
| width | number | No | |
|
||||
| is_tug | boolean | No | |
|
||||
| bollard_pull | integer | No | |
|
||||
| eni | integer | No | BSMD internal use |
|
||||
| created | string | No | Readonly field set by the database when ship was created |
|
||||
| modified | string | No | Readonly field set by the database when ship was last modified |
|
||||
| deleted | boolean | No | marks the ship as logically deleted |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **201**
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
### `PUT /ships`
|
||||
**Summary:** Update a ship entry
|
||||
Updating a ship entry. Please do not modify the IMO number. In that case please add a new entry.
|
||||
|
||||
#### Request Body
|
||||
Updated ship entry. The id parameter is **required**.
|
||||
|
||||
**JSON Schema**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| id | integer | No | |
|
||||
| name | string | No | |
|
||||
| imo | integer | No | |
|
||||
| callsign | string | No | |
|
||||
| participant_id | integer | No | Optional reference to participant (tug role) |
|
||||
| length | number | No | |
|
||||
| width | number | No | |
|
||||
| is_tug | boolean | No | |
|
||||
| bollard_pull | integer | No | |
|
||||
| eni | integer | No | BSMD internal use |
|
||||
| created | string | No | Readonly field set by the database when ship was created |
|
||||
| modified | string | No | Readonly field set by the database when ship was last modified |
|
||||
| deleted | boolean | No | marks the ship as logically deleted |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
## Shipcall Endpoints
|
||||
|
||||
### `GET /shipcalls`
|
||||
**Summary:** Gets a list of ship calls
|
||||
Get current ship calls
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Type | Required | Description |
|
||||
|------|----|------|----------|-------------|
|
||||
| past_days | query | integer | No | number of days in the past to include in the result. *Example: 7*. |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**: ship call list
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
### `POST /shipcalls`
|
||||
**Summary:** Create a new ship call
|
||||
A new shipcall is created without times at this point. This is ususally done by the BSMD or a participant with that particular role.
|
||||
|
||||
#### Request Body
|
||||
Creates a new ship call. **Do not** provide id parameter.
|
||||
|
||||
**JSON Schema**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| id | integer | No | |
|
||||
| ship_id | integer | Yes | |
|
||||
| port_id | integer | No | |
|
||||
| type | string | Yes | Type of ship call |
|
||||
| eta | string | No | |
|
||||
| voyage | string | No | |
|
||||
| etd | string | No | |
|
||||
| arrival_berth_id | integer | No | |
|
||||
| departure_berth_id | integer | No | |
|
||||
| tug_required | boolean | No | |
|
||||
| pilot_required | boolean | No | |
|
||||
| flags | integer | No | |
|
||||
| pier_side | boolean | No | |
|
||||
| bunkering | boolean | No | |
|
||||
| replenishing_terminal | boolean | No | |
|
||||
| replenishing_lock | boolean | No | |
|
||||
| draft | number | No | |
|
||||
| tidal_window_from | string | No | |
|
||||
| tidal_window_to | string | No | |
|
||||
| rain_sensitive_cargo | boolean | No | |
|
||||
| recommended_tugs | integer | No | |
|
||||
| anchored | boolean | No | |
|
||||
| moored_lock | boolean | No | |
|
||||
| canceled | boolean | No | |
|
||||
| evaluation | string | No | Evaluation of the ship call |
|
||||
| evaluation_message | string | No | |
|
||||
| time_ref_point | integer | No | Physical reference point for all times given in shipcall and depending times entries |
|
||||
| participants | array<object> | No | |
|
||||
| created | string | No | Readonly field set by the database when shipcall was created |
|
||||
| modified | string | No | Readonly field set by the database when shipcall was last modified |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **201**
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
### `PUT /shipcalls`
|
||||
**Summary:** Updates a ship call
|
||||
Updates a shipcall. Usually done if the participant assignments change.
|
||||
|
||||
#### Request Body
|
||||
Creates a new ship call. The id parameter is **required**.
|
||||
|
||||
**JSON Schema**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| id | integer | No | |
|
||||
| ship_id | integer | Yes | |
|
||||
| port_id | integer | No | |
|
||||
| type | string | Yes | Type of ship call |
|
||||
| eta | string | No | |
|
||||
| voyage | string | No | |
|
||||
| etd | string | No | |
|
||||
| arrival_berth_id | integer | No | |
|
||||
| departure_berth_id | integer | No | |
|
||||
| tug_required | boolean | No | |
|
||||
| pilot_required | boolean | No | |
|
||||
| flags | integer | No | |
|
||||
| pier_side | boolean | No | |
|
||||
| bunkering | boolean | No | |
|
||||
| replenishing_terminal | boolean | No | |
|
||||
| replenishing_lock | boolean | No | |
|
||||
| draft | number | No | |
|
||||
| tidal_window_from | string | No | |
|
||||
| tidal_window_to | string | No | |
|
||||
| rain_sensitive_cargo | boolean | No | |
|
||||
| recommended_tugs | integer | No | |
|
||||
| anchored | boolean | No | |
|
||||
| moored_lock | boolean | No | |
|
||||
| canceled | boolean | No | |
|
||||
| evaluation | string | No | Evaluation of the ship call |
|
||||
| evaluation_message | string | No | |
|
||||
| time_ref_point | integer | No | Physical reference point for all times given in shipcall and depending times entries |
|
||||
| participants | array<object> | No | |
|
||||
| created | string | No | Readonly field set by the database when shipcall was created |
|
||||
| modified | string | No | Readonly field set by the database when shipcall was last modified |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
## Static Endpoints
|
||||
|
||||
### `GET /berths`
|
||||
**Summary:** Gets a list of all berths registered
|
||||
Returns a list of berths, including berths that are (logically) deleted
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**: list of berths
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
### `GET /history`
|
||||
**Summary:** History data
|
||||
This endpoint returns a list of changes made to the specific shipcall
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Type | Required | Description |
|
||||
|------|----|------|----------|-------------|
|
||||
| shipcall_id | query | integer | Yes | **Id of ship call**. *Example: 3*. Id given in ship call list |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**: list of history entries
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
### `GET /notifications`
|
||||
**Summary:** Gets a list of notifications pursuant to a specified participant and ship call
|
||||
List of notifications (tbd)
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Type | Required | Description |
|
||||
|------|----|------|----------|-------------|
|
||||
| shipcall_id | query | integer | No | **Id of ship call**. *Example: 52*. Id given in ship call list |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**: notification list
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
### `GET /participants`
|
||||
**Summary:** gets one or all participants
|
||||
If no parameter is given, all participants are returned. The list can be used to display participant information in the context of ship calls.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Type | Required | Description |
|
||||
|------|----|------|----------|-------------|
|
||||
| user_id | query | integer | No | **Id of user**. *Example: 2*. User id returned by verify call. |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**: one or all participants as list
|
||||
- **400**
|
||||
- **401**
|
||||
- **404**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
### `GET /ports`
|
||||
**Summary:** Your GET endpoint
|
||||
Returns a list of ports
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**: list of ports
|
||||
- **401**
|
||||
- **403**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
## Times Endpoints
|
||||
|
||||
### `DELETE /times`
|
||||
**Summary:** Delete a times entry for a ship call.
|
||||
A times entry is typically deleted if the agent for example changes or removes the participant assignment for a particular role.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Type | Required | Description |
|
||||
|------|----|------|----------|-------------|
|
||||
| id | query | integer | Yes | **Id of times**. *Example: 42*. Id of times entry to be deleted. |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
### `GET /times`
|
||||
**Summary:** Gets list of times
|
||||
Get all times assigned to a shipcall. These might not be complete.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | In | Type | Required | Description |
|
||||
|------|----|------|----------|-------------|
|
||||
| shipcall_id | query | integer | No | **Id**. *Example: 42*. Id of referenced ship call. |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**: list of recorded times
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
### `POST /times`
|
||||
**Summary:** Create a new times entry for a ship call
|
||||
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.
|
||||
|
||||
#### Request Body
|
||||
Times entry that will be added to the ship call. **Do not** provide id parameter.
|
||||
|
||||
**JSON Schema**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| id | integer | No | |
|
||||
| eta_berth | string | No | Arrival time at berth |
|
||||
| eta_berth_fixed | boolean | No | If true, the eta is fixed and cannot be changed |
|
||||
| etd_berth | string | No | departure time from berth |
|
||||
| etd_berth_fixed | boolean | No | If true, the etd is fixed and cannot be changed |
|
||||
| lock_time | string | No | arrival time at lock |
|
||||
| lock_time_fixed | boolean | No | If true, the lock time is fixed and cannot be changed |
|
||||
| zone_entry | string | No | Expected time of entry into the zone |
|
||||
| zone_entry_fixed | boolean | No | If true, the zone entry time is fixed and cannot be changed |
|
||||
| operations_start | string | No | Start time for terminal operations |
|
||||
| operations_end | string | No | End time for terminal operations |
|
||||
| remarks | string | No | Additional remarks |
|
||||
| shipcall_id | integer | Yes | Reference to a shipcall id |
|
||||
| participant_id | integer | Yes | Reference to a participant id |
|
||||
| berth_id | integer | No | Reference to a berth id |
|
||||
| berth_info | string | No | Additional info text for berth |
|
||||
| pier_side | boolean | No | true if ship is rotated, false otherwise |
|
||||
| participant_type | integer | No | |
|
||||
| ata | string | No | ata can be set by mooring if actual times are different from planned |
|
||||
| atd | string | No | atd can be set by mooring if actual times are different from planned |
|
||||
| eta_interval_end | string | No | Optional end of the interval for the times eta entry |
|
||||
| etd_interval_end | string | No | Optional end of the interval for the times etd entry |
|
||||
| created | string | No | Readonly field set by the database when times record was created |
|
||||
| modified | string | No | Readonly field set by the database when times record was last modified |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **201**
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
### `PUT /times`
|
||||
**Summary:** Update a times entry for a ship call
|
||||
Updating a times entry for a ship for a particular participant. The times entries are required for a shipcall to pass the validation rules.
|
||||
|
||||
#### Request Body
|
||||
Times entry that will be added to the ship call. The id parameter is **required**.
|
||||
|
||||
**JSON Schema**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| id | integer | No | |
|
||||
| eta_berth | string | No | Arrival time at berth |
|
||||
| eta_berth_fixed | boolean | No | If true, the eta is fixed and cannot be changed |
|
||||
| etd_berth | string | No | departure time from berth |
|
||||
| etd_berth_fixed | boolean | No | If true, the etd is fixed and cannot be changed |
|
||||
| lock_time | string | No | arrival time at lock |
|
||||
| lock_time_fixed | boolean | No | If true, the lock time is fixed and cannot be changed |
|
||||
| zone_entry | string | No | Expected time of entry into the zone |
|
||||
| zone_entry_fixed | boolean | No | If true, the zone entry time is fixed and cannot be changed |
|
||||
| operations_start | string | No | Start time for terminal operations |
|
||||
| operations_end | string | No | End time for terminal operations |
|
||||
| remarks | string | No | Additional remarks |
|
||||
| shipcall_id | integer | Yes | Reference to a shipcall id |
|
||||
| participant_id | integer | Yes | Reference to a participant id |
|
||||
| berth_id | integer | No | Reference to a berth id |
|
||||
| berth_info | string | No | Additional info text for berth |
|
||||
| pier_side | boolean | No | true if ship is rotated, false otherwise |
|
||||
| participant_type | integer | No | |
|
||||
| ata | string | No | ata can be set by mooring if actual times are different from planned |
|
||||
| atd | string | No | atd can be set by mooring if actual times are different from planned |
|
||||
| eta_interval_end | string | No | Optional end of the interval for the times eta entry |
|
||||
| etd_interval_end | string | No | Optional end of the interval for the times etd entry |
|
||||
| created | string | No | Readonly field set by the database when times record was created |
|
||||
| modified | string | No | Readonly field set by the database when times record was last modified |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
|
||||
## User Endpoints
|
||||
|
||||
### `POST /login`
|
||||
**Summary:** Returns a JWT session token and user data if successful
|
||||
Perform login
|
||||
|
||||
#### Request Body
|
||||
Login credentials
|
||||
|
||||
**JSON Schema**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| username | string | Yes | |
|
||||
| password | string | Yes | |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**: Successful response
|
||||
- **400**
|
||||
- **403**
|
||||
- **500**
|
||||
- **503**
|
||||
|
||||
**Response 200 JSON Schema**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| id | integer | No | |
|
||||
| participant_id | integer | No | |
|
||||
| first_name | string | No | |
|
||||
| last_name | string | No | |
|
||||
| user_name | string | No | |
|
||||
| user_phone | string | No | |
|
||||
| user_email | string | No | |
|
||||
| notify_email | boolean | No | |
|
||||
| notify_whatsapp | boolean | No | |
|
||||
| notify_signal | boolean | No | |
|
||||
| notify_popup | boolean | No | |
|
||||
| exp | number | No | |
|
||||
| token | string | No | |
|
||||
| notify_on | array<string> | No | |
|
||||
|
||||
---
|
||||
|
||||
### `PUT /user`
|
||||
**Summary:** Update user details (first/last name, phone, password)
|
||||
Update user information
|
||||
|
||||
#### Request Body
|
||||
User details
|
||||
|
||||
**JSON Schema**
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| id | integer | No | |
|
||||
| old_password | string | No | |
|
||||
| new_password | string | No | |
|
||||
| first_name | string | No | |
|
||||
| last_name | string | No | |
|
||||
| user_phone | string | No | |
|
||||
| user_email | string | No | |
|
||||
| notify_email | boolean | No | |
|
||||
| notify_popup | boolean | No | |
|
||||
| notify_whatsapp | boolean | No | |
|
||||
| notify_signal | boolean | No | |
|
||||
| notify_on | array<string> | No | |
|
||||
|
||||
#### Responses
|
||||
|
||||
- **200**
|
||||
- **400**
|
||||
- **401**
|
||||
- **500**
|
||||
- **503**
|
||||
---
|
||||
@ -22,6 +22,8 @@ tags:
|
||||
- name: times
|
||||
- name: static
|
||||
- name: ship
|
||||
- name: notification
|
||||
- name: history
|
||||
paths:
|
||||
/login:
|
||||
post:
|
||||
@ -30,6 +32,7 @@ paths:
|
||||
tags:
|
||||
- user
|
||||
operationId: login
|
||||
security: []
|
||||
requestBody:
|
||||
description: Login credentials
|
||||
required: true
|
||||
@ -256,7 +259,7 @@ paths:
|
||||
- shipcall
|
||||
operationId: shipcallUpdate
|
||||
requestBody:
|
||||
description: Creates a new ship call. The id parameter is **required**.
|
||||
description: Updates a ship call. The id parameter is **required**.
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
@ -443,7 +446,7 @@ paths:
|
||||
- name: user_id
|
||||
in: query
|
||||
required: false
|
||||
description: '**Id of user**. *Example: 2*. User id returned by verify call.'
|
||||
description: '**Id of user**. *Example: 2*. User id returned by login call.'
|
||||
schema:
|
||||
type: integer
|
||||
example: 2
|
||||
@ -581,7 +584,7 @@ paths:
|
||||
- times
|
||||
operationId: timesUpdate
|
||||
requestBody:
|
||||
description: Times entry that will be added to the ship call. The id parameter is **required**.
|
||||
description: Times entry that will be updated for the ship call. The id parameter is **required**.
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
@ -649,10 +652,10 @@ paths:
|
||||
$ref: '#/components/responses/503'
|
||||
/notifications:
|
||||
get:
|
||||
summary: Gets a list of notifications pursuant to a specified participant and ship call
|
||||
summary: Gets a list of notifications pursuant to a specified ship call
|
||||
description: List of notifications (tbd)
|
||||
tags:
|
||||
- static
|
||||
- notification
|
||||
operationId: notificationsGet
|
||||
parameters:
|
||||
- name: shipcall_id
|
||||
@ -723,7 +726,7 @@ paths:
|
||||
description: This endpoint returns a list of changes made to the specific shipcall
|
||||
summary: History data
|
||||
tags:
|
||||
- static
|
||||
- history
|
||||
operationId: historyGet
|
||||
parameters:
|
||||
- name: shipcall_id
|
||||
@ -1756,10 +1759,11 @@ components:
|
||||
token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
|
||||
user_details:
|
||||
type: object
|
||||
description: fields that a user may change
|
||||
description: user metadata and editable fields
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
readOnly: true
|
||||
example: 42
|
||||
old_password:
|
||||
type: string
|
||||
|
||||
Loading…
Reference in New Issue
Block a user