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

Merge pull request #26 from puls200/feature/api_validation_rules

Browse Source 
Feature/api validation rules
This commit is contained in:
Daniel Schick 2024-04-10 15:22:27 +02:00 committed by GitHub
commit 8e8f9d6d3e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 226 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

226
docs/ApiValidationRules.md Normal file
View File

@ -0,0 +1,226 @@
# 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
## Change history
|Date|Edit|Author|
|--|--|--|
|2.2.24 | Document created, first draft | 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"
}
```
### 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.
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 |
#### 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.
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)
#### 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.
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 |
#### 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.
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
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
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.
2. The dataset may not be deleted already.