From cc724bdb3019f551c9b3f95f5861e9e396d7c104 Mon Sep 17 00:00:00 2001 From: Daniel Schick Date: Thu, 25 Jul 2024 11:13:51 +0200 Subject: [PATCH] Updated validation rule documentation --- docs/ApiValidationRules.md | 48 +++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/ApiValidationRules.md b/docs/ApiValidationRules.md index 701a681..40788b7 100644 --- a/docs/ApiValidationRules.md +++ b/docs/ApiValidationRules.md @@ -10,7 +10,8 @@ ___ |Date|Edit|Author| |--|--|--| -|2.2.24 | Document created, first draft | Daniel Schick | +| 2.2.24 | Document created, first draft | Daniel Schick | +| 25.7.24 | Update for BC 1.4 and other changes | Daniel Schick | ## Global constants and definitions @@ -50,7 +51,7 @@ The shipcall type which is set in the shipcall record may have the following val ### Token evaluation -The identity of the caller can be retrieved from the token. This contains an id (="user id") and more importantly, the "participant_id". Every call is only allow if the user is properly authorized to perform the call or modify the dataset. +The identity of the caller can be retrieved from the token. This contains an id (="user id") and more importantly, the "participant_id". Every call is only allow if the user is properly authorized to perform the call or modify the dataset. At this time, authorization is performed on a participant level. This means that all users that belong to a particular participant have the same rights. @@ -78,21 +79,20 @@ Date and date+time values are specified as text formatted in [RFC 3339](https:// } ``` -Usually the "Z" is missing at the end indicating local time. +Usually the "Z" is missing at the end indicating local time. ## /shipcall POST 1. The call may only be performed by a user belonging to participant group type BSMD. 2. Reference checking: The dataset includes multiple fields referring other tables. The validation must make sure the referenced entities exist. This includes the following fields: - | Field | Referenced table | - |-------|------------------| - | ship_id | ship | - | arrival_berth_id | berth | - | departure_berth_id | berth | - | participants | 1. participant_id values may appear more once 2. types may only appear once and must not include type "BSMD".| - + | Field | Referenced table | Notes | + |-------|------------------| ----- | + | ship_id | ship | | + | arrival_berth_id | berth | required if type is "arrival" (1) | + | departure_berth_id | berth | required if type is "departure" or "shifting" (2 or 3) | + | participants | participant | This is a list containing participant_id and type pairs with the following rules: 1. participant_id values may appear more once 2. types may only appear once, therefore there are a maximum of 7 elements in this list. | -3. Check for reasonable values for the following fields: +3. Check for reasonable values for the following fields: | Field | Validation | |-------|------------| @@ -107,9 +107,11 @@ Usually the "Z" is missing at the end indicating local time. | recommended_tugs | 0 < value < 10 | | canceled | may not be set on POST | | evaluation | may not be set | - | evaluation_message | may not be set | + | evaluation_message | may not be set | + | created / modified | may not be set | #### Required fields + * eta / etd (depending on value of type: 1: eta, 2: etd, 3: both) * type * ship_id @@ -119,7 +121,7 @@ Usually the "Z" is missing at the end indicating local time. ## /shipcall PUT 1. The call may only be performed by a user belonging to participant group type BSMD. -2. If a agency is selected via the shipcall_participant_map entry, users of this agency may also edit the shipcall. Care has to be taken: The agency must have been set _before_ a member of the group may edit the record. +2. If a agency is selected via the shipcall_participant_map entry, users of this agency may also edit the shipcall. Care has to be taken: The agency must have been set _before_ a member of the group may edit the record. In other words: no setting the agency and editing the record by a member of the agency within the same call. 3. See value rules in /shipcall POST. Exception: Canceled may be set but only if not already set. 4. A cancelled shipcall may not be changed (is logical delete) @@ -140,7 +142,7 @@ The id field is required, missing fields will not be updated. | participant_id | participant | | berth_id | berth | -5. Check for reasonable values for the following fields: +5. Check for reasonable values for the following fields: | Field | Validation | |-------|------------| @@ -156,32 +158,31 @@ This depends on the shipcall and participant type: AGENCY, PILOT, PORT_AUTHORITY, MOORING, TUG: -eta_berth, shipcall_id, participant_id, participant_type +shipcall_id, participant_id, participant_type TERMINAL: -operations_start, shipcall_id, participant_id, participant_type +shipcall_id, participant_id, participant_type ##### Outgoing AGENCY, PILOT, PORT_AUTHORITY, MOORING, TUG: -etd_berth, shipcall_id, participant_id, participant_type +shipcall_id, participant_id, participant_type TERMINAL: -operations_end, shipcall_id, participant_id, participant_type +shipcall_id, participant_id, participant_type ##### Shifting AGENCY, PILOT, PORT_AUTHORITY, MOORING, TUG: -eta_berth, etd_berth, shipcall_id, participant_id, participant_type +shipcall_id, participant_id, participant_type TERMINAL: -operations_start, operations_end, shipcall_id, participant_id, participant_type - +shipcall_id, participant_id, participant_type ## /times PUT @@ -190,7 +191,7 @@ operations_start, operations_end, shipcall_id, participant_id, participant_type #### Required fields -The id field is required, missing fields will not be updated. +The id field is required, missing fields will not be updated ## /times DELETE @@ -201,7 +202,7 @@ The id field is required, missing fields will not be updated. 1. The call may only be performed by a user belonging to participant group type BSMD. 2. A ship may only be added if there is no other ship with the same IMO number already present in the database. -3. Check for reasonable values for the following fields: +3. Check for reasonable values for the following fields: | Field | Validation | |-------|------------| @@ -219,7 +220,6 @@ The id field is required, missing fields will not be updated. 3. See value rules in /ship POST 4. The id field is required, missing fields will not be updated - ## /ship DELETE 1. The call may only be performed by a user belonging to participant group type BSMD.