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
25.7.24	Update for BC 1.4 and other changes	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"
}

Time values

Date and date+time values are specified as text formatted in RFC 3339, e.g.

{
    "created" : "2024-01-27T18:00:21Z"
}

Usually the "Z" is missing at the end indicating local time.

/shipcall POST

The call may only be performed by a user belonging to participant group type BSMD.

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	Notes
ship_id	ship
arrival_berth_id	berth	required if type is "arrival" (1)
departure_berth_id	berth	required if type is "departure" or "shifting" (2 or 3)
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.

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	optional on POST
evaluation	may not be set
evaluation_message	may not be set
created / modified	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

The call may only be performed by a user belonging to participant group type BSMD.
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.
See value rules in /shipcall POST. Exception: Canceled may be set but only if not already set.
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

A new dataset may only be created by a user not belonging to participant group BSMD.
A new dataset may only be created if a dataset of this type is not already present for the participant type.
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.
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

Field	Referenced table
shipcall_id	shipcall
participant_id	participant
berth_id	berth

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
eta_interval_end, etd_interval_end	if set these values must be in the future. They must be larger than their ETA/ETD counterparts.
remarks, berth_info	must be <= 512 chars
participant_type	must not be BSMD