From 91168412923e2e285a7d1d169bb9edff19757acf Mon Sep 17 00:00:00 2001 From: Daniel Schick Date: Fri, 14 Nov 2025 11:19:04 +0100 Subject: [PATCH] Added a documentation file for the API spec --- misc/BreCalApi.md | 526 ++++++++++++++++++++++++++++++++++++++++++++ misc/BreCalApi.yaml | 18 +- 2 files changed, 537 insertions(+), 7 deletions(-) create mode 100644 misc/BreCalApi.md diff --git a/misc/BreCalApi.md b/misc/BreCalApi.md new file mode 100644 index 0000000..381842a --- /dev/null +++ b/misc/BreCalApi.md @@ -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 | 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 | 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 | 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 | No | | + +#### Responses + +- **200** +- **400** +- **401** +- **500** +- **503** +--- diff --git a/misc/BreCalApi.yaml b/misc/BreCalApi.yaml index 77ae767..fc33cf2 100644 --- a/misc/BreCalApi.yaml +++ b/misc/BreCalApi.yaml @@ -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