From 2a7cf2119be075f984d383d96d3624a0a6513f4c Mon Sep 17 00:00:00 2001 From: Daniel Schick Date: Sun, 21 Jan 2024 11:21:27 +0100 Subject: [PATCH 1/5] created an empty document --- docs/ApiValidationRules.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/ApiValidationRules.md diff --git a/docs/ApiValidationRules.md b/docs/ApiValidationRules.md new file mode 100644 index 0000000..e1655b6 --- /dev/null +++ b/docs/ApiValidationRules.md @@ -0,0 +1,23 @@ +# Rest-API validation rules for the backend + +___ + +* Rules defined here only apply to calls that change data (POST / PUT /DELETE requests) +* Violation of these rules should result in 400 bad request +* These are not high-level rules that change color of a data entry in the app + +## /shipcall POST + +## /shipcall PUT + +## /times POST + +## /times PUT + +## /times DELETE + +## /ship POST + +## /ship PUT + +## /ship DELETE \ No newline at end of file From 01eb7999f86d423597c7f0c54e909b3733c4c55f Mon Sep 17 00:00:00 2001 From: Daniel Schick Date: Fri, 2 Feb 2024 09:57:05 +0100 Subject: [PATCH 2/5] Created first draft --- docs/ApiValidationRules.md | 143 ++++++++++++++++++++++++++++++++++++- 1 file changed, 142 insertions(+), 1 deletion(-) diff --git a/docs/ApiValidationRules.md b/docs/ApiValidationRules.md index e1655b6..1ab9b05 100644 --- a/docs/ApiValidationRules.md +++ b/docs/ApiValidationRules.md @@ -6,18 +6,159 @@ ___ * Violation of these rules should result in 400 bad request * These are not high-level rules that change color of a data entry in the app +## Change history + +|Date|Edit|Author| +|--|--|--| +|2.2.24 | Document created | Daniel Schick | + +## Global constants and definitions + +### Participant type + +The participant type is a bit flag that encodes which user groups a participant belongs to. Note: A participant may belong to **multiple** groups so this flag has to be bitwise evaluated. + +|Value|Group| +|-----|-----| +| 1 | BSMD | +| 2 | Terminal | +| 4 | Pilot | +| 8 | Agency | +| 16 | Mooring | +| 32 | Port authority | +| 64 | Tug | + +### Participant flag + +The participant data record contains a field called "flag" which is also bitwise encoded. The purpose of this flag is to allow user authorization on a finer level. Currently the following flag(s) are defined: + +| Value | Significance | +| ------|--------------| +| 1 | If this flag is set on a shipcall record with participant type Agency (8), all participants of type BSMD (1) may edit the record. + +### Shipcall type + +The shipcall type which is set in the shipcall record may have the following values + +| Value | Meaning | +|-------|---------| +| 1 | Incoming | +| 2 | Outgoing | +| 3 | Shifting (changing berths) | + +## All queries + +### 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. + +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. + +### Modifying unknown entities + +PUT / DELETE calls referencing entities that are not found in the database will receive an 404 reply. This is already implemented in the underlying code and therefore not mentioned in this document. This evaluation should precede the API validation so in this document we assume the entities are existing. + +### Return value + +If a validation rule fails the call should return 400 (Bad request) including an error message in the format already in use: + +```json +{ + "message" : "reason why this call failed" +} +``` + ## /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".| + + +3. Check for reasonable values for the following fields: + + | Field | Validation | + |-------|------------| + | eta | value must be in the future | + | type | value must be one of the values defined above | + | voyage | if set must be <= 16 chars and no special characters | + | etd | must be in the future | + | flags | must be a combination of the flags defined above | + | draft | 0 <= value <= 20 | + | tidal_window_from | value must be in the future | + | tidal_window_to | value must be in the future, value must be > tidal_window_from | + | recommended_tugs | 0 < value < 10 | + | canceled | may not be set on POST | + | evaluation | may not be set | + | evaluation_message | may not be set | + ## /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. +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) + ## /times POST +1. A new dataset may only be created by a user _not_ belonging to participant group BSMD. +2. A new dataset may only be created if a dataset of this type is not already present for the participant type. +3. A new dataset may only be created if the user belongs to the participant group assigned to the shipcall with the appropriate type (see shipcall_participant_map). This actually trumps rule #1 but may return a different error message. +4. 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 | + |-------|------------------| + | shipcall_id | shipcall | + | participant_id | participant | + | berth_id | berth | + +5. Check for reasonable values for the following fields: + + | Field | Validation | + |-------|------------| + | eta_berth, etd_berth, lock_time, zone_entry, operations_start, operations_end | if set these values must be in the future| + | remarks, berth_info | must be <= 512 chars | + | participant_type | must not be BSMD | + + ## /times PUT +1. A dataset may only be changed by a user belonging to the same participant as the times dataset is referring to. +2. See reference and value checking as specified in /times POST. + ## /times DELETE +1. A dataset may only be changed by a user belonging to the same participant as the times dataset is referring to. +2. The dataset may not be deleted already. + ## /ship POST +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: + + | Field | Validation | + |-------|------------| + | name | Length < 64, no special characters | + | IMO | 7-digit number. See [here](https://de.wikipedia.org/wiki/IMO-Nummer) for clarification. | + | callsign | Length <= 8, no special characters | + | Length | 0 < value < 1000 | + | Width | 0 < value < 100 | + | bollard_pull | 0 < value < 500, only allowed if is_tug = 1 | + ## /ship PUT -## /ship DELETE \ No newline at end of file +1. The call may only be performed by a user belonging to participant group type BSMD. +2. The IMO number field may not be changed since it serves the purpose of a primary (matching) key. +3. See value rules in /ship POST. + + +## /ship DELETE + +1. The call may only be performed by a user belonging to participant group type BSMD. +2. The dataset may not be deleted already. From 6bc57cf31d321faea73fd6d285f3d5234b9fe90c Mon Sep 17 00:00:00 2001 From: Daniel Schick Date: Fri, 2 Feb 2024 10:23:02 +0100 Subject: [PATCH 3/5] added missing change --- docs/ApiValidationRules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ApiValidationRules.md b/docs/ApiValidationRules.md index 1ab9b05..c769c31 100644 --- a/docs/ApiValidationRules.md +++ b/docs/ApiValidationRules.md @@ -10,7 +10,7 @@ ___ |Date|Edit|Author| |--|--|--| -|2.2.24 | Document created | Daniel Schick | +|2.2.24 | Document created, first draft | Daniel Schick | ## Global constants and definitions @@ -124,7 +124,7 @@ In other words: no setting the agency and editing the record by a member of the | eta_berth, etd_berth, lock_time, zone_entry, operations_start, operations_end | if set these values must be in the future| | remarks, berth_info | must be <= 512 chars | | participant_type | must not be BSMD | - + ## /times PUT From 4e34a536c7626740b3d7e9798185b80afcc53a04 Mon Sep 17 00:00:00 2001 From: Daniel Schick Date: Fri, 2 Feb 2024 13:29:01 +0100 Subject: [PATCH 4/5] added required fields --- docs/ApiValidationRules.md | 52 +++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/docs/ApiValidationRules.md b/docs/ApiValidationRules.md index c769c31..9cf2073 100644 --- a/docs/ApiValidationRules.md +++ b/docs/ApiValidationRules.md @@ -97,6 +97,13 @@ If a validation rule fails the call should return 400 (Bad request) including an | evaluation | may not be set | | evaluation_message | may not be set | +#### Required fields +* eta / etd (depending on value of type: 1: eta, 2: etd, 3: both) +* type +* ship_id +* arrival_berth_id / departure_berth_id (depending on type, see above) +* assigned participant for agency + ## /shipcall PUT 1. The call may only be performed by a user belonging to participant group type BSMD. @@ -105,6 +112,10 @@ In other words: no setting the agency and editing the record by a member of the 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) +#### Required fields + +The id field is required, missing fields will not be updated. + ## /times POST 1. A new dataset may only be created by a user _not_ belonging to participant group BSMD. @@ -125,12 +136,50 @@ In other words: no setting the agency and editing the record by a member of the | remarks, berth_info | must be <= 512 chars | | participant_type | must not be BSMD | +#### Required fields + +This depends on the shipcall and participant type: + +##### Incoming + +AGENCY, PILOT, PORT_AUTHORITY, MOORING, TUG: + +eta_berth, shipcall_id, participant_id, participant_type + +TERMINAL: + +operations_start, shipcall_id, participant_id, participant_type + +##### Outgoing + +AGENCY, PILOT, PORT_AUTHORITY, MOORING, TUG: + +etd_berth, shipcall_id, participant_id, participant_type + +TERMINAL: + +operations_end, shipcall_id, participant_id, participant_type + +##### Shifting + +AGENCY, PILOT, PORT_AUTHORITY, MOORING, TUG: + +eta_berth, etd_berth, shipcall_id, participant_id, participant_type + +TERMINAL: + +operations_start, operations_end, shipcall_id, participant_id, participant_type + ## /times PUT 1. A dataset may only be changed by a user belonging to the same participant as the times dataset is referring to. 2. See reference and value checking as specified in /times POST. +#### Required fields + +The id field is required, missing fields will not be updated. + ## /times DELETE 1. A dataset may only be changed by a user belonging to the same participant as the times dataset is referring to. @@ -155,7 +204,8 @@ In other words: no setting the agency and editing the record by a member of the 1. The call may only be performed by a user belonging to participant group type BSMD. 2. The IMO number field may not be changed since it serves the purpose of a primary (matching) key. -3. See value rules in /ship POST. +3. See value rules in /ship POST +4. The id field is required, missing fields will not be updated ## /ship DELETE From 060d131cea1afc443f27292644f24537e0344d9c Mon Sep 17 00:00:00 2001 From: Daniel Schick Date: Wed, 14 Feb 2024 14:49:18 +0100 Subject: [PATCH 5/5] Clarified date/time format strings --- docs/ApiValidationRules.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/ApiValidationRules.md b/docs/ApiValidationRules.md index 9cf2073..701a681 100644 --- a/docs/ApiValidationRules.md +++ b/docs/ApiValidationRules.md @@ -68,6 +68,18 @@ If a validation rule fails the call should return 400 (Bad request) including an } ``` +### Time values + +Date and date+time values are specified as text formatted in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6), e.g. + +```json +{ + "created" : "2024-01-27T18:00:21Z" +} +``` + +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.