git_brcal/docs/ApiValidationRules.md

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	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:

{
    "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 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.