Grounding configurations
The Grounding detector is used to detect when a ship unintentionally makes contact with the seabed or an underwater obstruction. In marine informatics, grounding events serve as an important indicator of navigational safety and operational risk, as they identify when and where an impact occurs.
This article will explain a high level view of how to interact with the Gatehouse Maritime API to create, read, update, or delete grounding detectors, with high level illustrations of how to do it.
Content overview:
- Create Grounding Detector
- Read Events from a Grounding Detector
- Update a Grounding Detector
- Delete a Grounding Event Detector
Create Grounding Detector
The creation of a grounding detector is similar to creating a generic event detector in the system; however, a grounding detector has several parameters that is not used for a generic event detector.
To create a grounding detector in the system, a PUT request should be specified via the /configurations endpoint where the request body should specify the configuration of the detector.
By sending such a request, the API will construct an event detector in the system that will react upon the specified events.
The following is an image depicting the process of constructing a request and reaching the endpoint and how it responds to this:
Read Events from a Grounding Detector
Once a grounding detector has been created in the system, it is possible to see all logged events from a specific detector. This allows the user to create seamless integration with the API to get real-time updates of relevant events in the system.
To read events from at grounding detector, construct a GET request via the /configurations/{id} endpoint, where the id variable defines the id of the detector to acquire events from.
By accessing this endpoint, the API will respond with a list of items in Json-format that defines events that has been logged by the detector.
The following is an image that depicts the process of sending a request to the API and what the API will respond with:
Update a Grounding Detector
Once a grounding detector has been created within the system, it may be necessary to update its configuration. Updating a detector ensures that its behaviour continues to align with operational requirements.
To update a grounding detector, construct a PUT request (depending on the API’s specification) to the /configurations/{id} endpoint, where the id parameter identifies the specific detector, whose configuration is to be modified.
The body of the request must contain a JSON-formatted object describing the fields to be updated. Only the supplied fields will be altered; all other properties of the detector remain unchanged.
Upon receiving this request, the API validates the provided configuration values and, if successful, applies the updates to the detector. The response will contain the updated detector object in JSON format, confirming that the operation has been completed.
The following illustration depicts the client sending the update request and the API returning the revised configuration of the detector.
Delete a Grounding Event Detector
In some situations, a grounding detector may no longer be required. In such cases, the detector can be removed from the system.
To delete a grounding detector, construct a DELETE request to the /configurations/{id} endpoint, where the id parameter specifies the detector that is to be removed.
When this request is received, the API verifies that the detector exists and that it is eligible for deletion. If the operation is successful, the system removes the detector and all associated configuration data. The API then returns a confirmation response containing a status code of 204.
After deletion, the detector will no longer appear in subsequent queries, and any attempts to access or update it will result in an error response indicating that the resource cannot be found.
The following is an image depicting the process of reaching the API’s endpoint and its’ response regarding the deletion of the detector:
