Created first draft
This commit is contained in:
parent
2a7cf2119b
commit
01eb7999f8
@ -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
|
||||
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user