dschick/BreCal
dschick/BreCal
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated validation rule documentation

Browse Source
This commit is contained in:
Daniel Schick 2024-07-25 11:13:51 +02:00
parent cd8c246d72
commit cc724bdb30
1 changed files with 24 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
docs/ApiValidationRules.md
View File

@ -10,7 +10,8 @@ ___
|Date|Edit|Author| |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 ## 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 ### 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. 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 ## /shipcall POST
1. The call may only be performed by a user belonging to participant group type BSMD. 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: 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 | | Field | Referenced table | Notes |
|-------|------------------| |-------|------------------| ----- |
| ship_id | ship | | ship_id | ship | |
| arrival_berth_id | berth | | arrival_berth_id | berth | required if type is "arrival" (1) |
| departure_berth_id | berth | | departure_berth_id | berth | required if type is "departure" or "shifting" (2 or 3) |
| participants | 1. participant_id values may appear more once 2. types may only appear once and must not include type "BSMD".| | 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 | | Field | Validation |
|-------|------------| |-------|------------|
@ -107,9 +107,11 @@ Usually the "Z" is missing at the end indicating local time.
| recommended_tugs | 0 < value < 10 | | recommended_tugs | 0 < value < 10 |
| canceled | may not be set on POST | | canceled | may not be set on POST |
| evaluation | may not be set | | 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 #### Required fields
* eta / etd (depending on value of type: 1: eta, 2: etd, 3: both) * eta / etd (depending on value of type: 1: eta, 2: etd, 3: both)
* type * type
* ship_id * ship_id
@ -119,7 +121,7 @@ Usually the "Z" is missing at the end indicating local time.
## /shipcall PUT ## /shipcall PUT
1. The call may only be performed by a user belonging to participant group type BSMD. 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. 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. 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) 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 | | participant_id | participant |
| berth_id | berth | | berth_id | berth |
5. Check for reasonable values for the following fields: 5. Check for reasonable values for the following fields:
| Field | Validation | | Field | Validation |
|-------|------------| |-------|------------|
@ -156,32 +158,31 @@ This depends on the shipcall and participant type:
AGENCY, PILOT, PORT_AUTHORITY, MOORING, TUG: AGENCY, PILOT, PORT_AUTHORITY, MOORING, TUG:
eta_berth, shipcall_id, participant_id, participant_type shipcall_id, participant_id, participant_type
TERMINAL: TERMINAL:
operations_start, shipcall_id, participant_id, participant_type shipcall_id, participant_id, participant_type
##### Outgoing ##### Outgoing
AGENCY, PILOT, PORT_AUTHORITY, MOORING, TUG: AGENCY, PILOT, PORT_AUTHORITY, MOORING, TUG:
etd_berth, shipcall_id, participant_id, participant_type shipcall_id, participant_id, participant_type
TERMINAL: TERMINAL:
operations_end, shipcall_id, participant_id, participant_type shipcall_id, participant_id, participant_type
##### Shifting ##### Shifting
AGENCY, PILOT, PORT_AUTHORITY, MOORING, TUG: AGENCY, PILOT, PORT_AUTHORITY, MOORING, TUG:
eta_berth, etd_berth, shipcall_id, participant_id, participant_type shipcall_id, participant_id, participant_type
TERMINAL: TERMINAL:
operations_start, operations_end, shipcall_id, participant_id, participant_type shipcall_id, participant_id, participant_type
## /times PUT ## /times PUT
@ -190,7 +191,7 @@ operations_start, operations_end, shipcall_id, participant_id, participant_type
#### Required fields #### 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 ## /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. 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. 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 | | Field | Validation |
|-------|------------| |-------|------------|
@ -219,7 +220,6 @@ The id field is required, missing fields will not be updated.
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 4. The id field is required, missing fields will not be updated
## /ship DELETE ## /ship DELETE
1. The call may only be performed by a user belonging to participant group type BSMD. 1. The call may only be performed by a user belonging to participant group type BSMD.