Reefer Operational Monitoring Notification API

[cmsdroff]

User description

First draft for the RMO_NTF api to provide shallow notifications to be provided to carriers about reefer events.

---

PR Type

Enhancement, Documentation

---

Description

• Add Reefer Monitoring Operational (RMO) API specification with polling model

• Add RMO Notification (RMO_NTF) API for CloudEvents-based notifications

• Implement lightweight notification system for reefer alarm and geofence events

• Add comprehensive README documentation for both RMO and RMO_NTF APIs

---

Diagram Walkthrough

flowchart LR
  A["RMO API<br/>GET/POST /v1/events"] -->|Polling Model| B["Reefer Data<br/>Measurements & Alarms"]
  C["RMO_NTF API<br/>POST /v1/operational-reefer-notifications"] -->|CloudEvents| D["Notifications<br/>ALARM & GEOFENCE"]
  B -->|Triggers| D
  E["README Documentation"] -->|Describes| A
  E -->|Describes| C

Loading

File Walkthrough

	Relevant files
Documentation	README.md Add RMO API documentation and overview                                      rmo/v1/README.md Created README documenting the Reefer Monitoring Operational (RMO) API References SwaggerHub documentation and release information Provides link to v1.0.0-Beta-1 release notes +7/-0      README.md Add RMO_NTF API documentation and overview                              rmo/v1/notification/README.md Created README for RMO Notification (RMO_NTF) API Documents the CloudEvents-based notification specification References SwaggerHub and initial release information +7/-0
Enhancement	rmo_ntf_v1.0.0-Beta-1.yaml Implement RMO_NTF API with CloudEvents notifications          rmo/v1/notification/rmo_ntf_v1.0.0-Beta-1.yaml Defines OpenAPI 3.0.0 specification for operational reefer notifications Implements CloudEvents 1.0 format for notification payloads Provides POST endpoint for receiving ALARM and GEOFENCE notifications Includes comprehensive examples for alarm activation and deactivation scenarios Defines OperationalReeferNotification schema with equipment reference, geo-location, and alarm details +272/-0  rmo_v1.0.0-Beta-1.yaml Implement RMO API with polling and push models                      rmo/v1/rmo_v1.0.0-Beta-1.yaml Defines OpenAPI 3.0.0 specification for Reefer Monitoring Operational API Implements GET endpoint for polling reefer monitoring data with query filters Implements POST endpoint for pushing reefer data to container operators Defines comprehensive reeferResponse schema including controller, measurements, setpoints, alarms, and inspection data Includes detailed examples of reefer data retrieval by equipment reference Supports filtering by event datetime, equipment reference, and active controller alarms +842/-0

---

[cmsdroff]

@HenrikHL I have completed work on the RMO and RMO_NTF in stoplight.

• Removed the full type notifications as discussed,
• Updated with POST for the RMO api to provide reefer data to carriers
• Updated the Readme to match for consistency.
• Merged master to RMO_NTF

Im good to prepare to finalise our work on this, if you could give it the eyes over and push to swagger hub the unpublished API specs would be much appreciated.

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Missing auditing: The new API specifications define endpoints for posting and getting reefer data and posting notifications but do not specify audit/logging requirements for critical actions such as notifications delivered or data access events. Referred Code paths: /v1/events: get: tags: - Events summary: Retrieve Reefer Information description: Fetch the current monitoring data available for reefer container fleet operationId: fetchReefer parameters: - $ref: ../../domain/event/event_domain_v3.2.0.yaml#/components/parameters/eventDateTime - $ref: ../../domain/event/event_domain_v3.2.0.yaml#/components/parameters/equipmentReference - schema: type: boolean in: query name: activeControllerAlarms description: Will filter by all live reefers with one or more active alarms - name: API-Version in: header description: | An API-Version header **MUST** be provided to the request (mandatory). The header **MUST** be a [SemVer](https://semver.org/) specifying the provider (the calling party) API version. required: true ... (clipped 63 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Sparse errors: The spec defines a 404 example for GET but lacks explicit error responses and validation/error payloads for other failure cases (e.g., 400, 401, 429, 5xx) on GET/POST, leaving edge cases and actionable error context unspecified. Referred Code description: Not Found content: application/json: example: httpMethod: GET requestUri: /v1/events statusCode: 404 statusCodeText: Not Found statusCodeMessage: Either no container found or no events to report errorDateTime: '2024-01-23T07:41:00+08:30' errors: - errorCodeText: No reefer data available errorCodeMessage: Either no container found or no events to report for given reefer container post: summary: Provide Reefer Information Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Error exposure risk: Error schema/examples are minimal and there is no guidance ensuring user-facing errors remain generic and internal details (e.g., stack traces) are confined to logs. Referred Code description: Not Found content: application/json: example: httpMethod: GET requestUri: /v1/events statusCode: 404 statusCodeText: Not Found statusCodeMessage: Either no container found or no events to report errorDateTime: '2024-01-23T07:41:00+08:30' errors: - errorCodeText: No reefer data available errorCodeMessage: Either no container found or no events to report for given reefer container post: summary: Provide Reefer Information Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Logging undefined: The specifications do not state logging structure or redaction requirements for request/response handling, leaving risk of sensitive operational data being logged without safeguards. Referred Code - url: 'http://localhost:3000' paths: /v1/operational-reefer-notifications: post: tags: - Notifications summary: Send a new Operational Reefer Notification operationId: operational-reefer-notifications description: | Creates a new [`Operational Reefer Notification`](#/OperationalReeferNotification). This endpoint of the consumer is called whenever a `Reefer` that is being subscribed to meets the agreed notification criteria. parameters: - name: API-Version in: header description: | An API-Version header **MUST** be provided to the request (mandatory). The header **MUST** be a [SemVer](https://semver.org/) specifying the provider (the calling party) API version. required: true schema: type: string example: 1.0.0-Beta-1 requestBody: description: | ... (clipped 67 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Validation gaps: While schemas constrain many fields, the APIs lack explicit security controls like authentication/authorization requirements, rate limits, and comprehensive request validation/error responses, especially for the POST notification consumer endpoint. Referred Code /v1/operational-reefer-notifications: post: tags: - Notifications summary: Send a new Operational Reefer Notification operationId: operational-reefer-notifications description: | Creates a new [`Operational Reefer Notification`](#/OperationalReeferNotification). This endpoint of the consumer is called whenever a `Reefer` that is being subscribed to meets the agreed notification criteria. parameters: - name: API-Version in: header description: | An API-Version header **MUST** be provided to the request (mandatory). The header **MUST** be a [SemVer](https://semver.org/) specifying the provider (the calling party) API version. required: true schema: type: string example: 1.0.0-Beta-1 requestBody: description: | The payload used to create a [`Operational Reefer Notification`](#/OperationalReeferNotification) content: ... (clipped 65 lines) Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Enforce allowed values with enum Add an enum constraint to the alarmStatus field to enforce the allowed values of ACTIVE and INACTIVE. rmo/v1/notification/rmo_ntf_v1.0.0-Beta-1.yaml [225-233] alarmStatus: type: string x-stoplight: id: h63fl95ba6npl description: |- Indicates if the alarm is active or inactive. Possible values are: * `ACTIVE` meaning the alarm has been activated. * `INACTIVE` meaning the alarm is no longer active. example: ACTIVE + enum: + - ACTIVE + - INACTIVE Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly points out that the alarmStatus field should use an enum to enforce the documented values, which improves the schema's strictness and data integrity.	Medium
	Refine regex to disallow spaces Refine the regex for equipmentReference to disallow whitespace, aligning it with standard identifier formats. rmo/v1/notification/rmo_ntf_v1.0.0-Beta-1.yaml [208-209] -pattern: ^\S+(\s+\S+)*$ +pattern: '^\S{1,11}$' maxLength: 11 Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that the regex for equipmentReference is too permissive by allowing whitespace, and proposes a stricter pattern that aligns better with identifier standards like ISO 6346.	Low
More