In technical terms, lightweight notifications in APIs (Application Programming Interfaces) refer to a messaging pattern where the API sends concise and focused messages to notify clients or subscribers about specific events or changes. These notifications are designed to be minimalistic in terms of data payload and typically contain only essential information such as identifiers or key data elements relevant to the event, allowing the recipient to understand the context and take appropriate action without the need for extensive data transfer.
Lightweight notifications have been applied across DCSA standard-based APIs, replacing shipment events as a push mechanism for real-time updates. All parties can independently and optionally subscribe to lightweight notifications supporting the Booking process defined in this standard. If subscribed, the API consumer (e.g. Shipper) is notified whenever the state or content of a Booking or Booking amendment changes, eliminating their need to proactively poll the GET endpoints for updates. With the transition from polling to lightweight notifications, Carriers benefit from reduced load on their systems, and all parties benefit from reduced network traffic and improved business process latency, facilitating efficient interaction between different systems.
The following applies whenever the Carrier sends a lightweight notification:
The Carrier independently sends the notification to each relevant counterpart who has registered to receive API notifications for the use cases of this standard. The registration mechanism, life cycle and any filtering are out of scope for this standard.
The Carrier sends the lightweight notifications asynchronously, after updating the state and/or content of the document in its own systems. If sending the lightweight notification fails, that does not constitute a use case exception and the Carrier must not revert any of the changes already performed in its own system: the relevant counterpart can be notified out of channel or will receive the update upon a subsequent GET request called to the same API for the same document.
If the Carrier cannot or does not want to accept the API request (e.g. when the Shipper requests to cancel a Booking amendment which is already being processed), it responds with the appropriate error message and HTTP status code. The Carrier does not change the state or content of the document, and it does not send a lightweight notification about the rejected API request.
A complete overview of the use cases below is illustrated in the DCSA Booking and BL State Transition Diagrams. The full list of data attributes that are relevant input for each use case is provided in the DCSA Booking process 2.0 Beta 1 Data overview.
# | Use case name | [Actor] to [Actor] |
---|---|---|
1 | Submit Booking request | Shipper to Carrier |
2 | Request to update Booking request | Carrier to Shipper |
3 | Submit updated Booking request | Shipper to Carrier |
4 | Reject Booking request | Carrier to Shipper |
5 | Confirm Booking request | Carrier to Shipper |
6 | Request to amend confirmed Booking | Carrier to Shipper |
7 | Request amendment to confirmed Booking | Shipper to Carrier |
8 | Process amendment to confirmed Booking | Carrier to Shipper |
9 | Cancel amendment to confirmed Booking | Shipper to Carrier |
10 | Decline Booking by Carrier | Carrier to Shipper |
11 | Cancel Booking by Shipper | Shipper to Carrier |
12 | Confirm Booking completed | Carrier to Shipper |
Shipper to Carrier
The Shipper submits the Booking request for a shipment.
The Shipper has sufficient information to submit a Booking request.
The Booking is in state RECEIVED.
Carrier to Shipper
The Carrier requests that the Shipper submits an update to the Booking request.
The Booking is in one of the following states:
The Booking is in state PENDING UPDATE.
Shipper to Carrier
The Shipper submits the updated Booking request.
The Booking is in one of the following states:
The Booking is in state UPDATE RECEIVED.
Carrier to Shipper
The Carrier rejects the Booking request received from the Shipper.
The Booking is in one of the following states:
RECEIVED
PENDING UPDATE
UPDATE RECEIVED
The Booking is in state REJECTED.
The Carrier decides to reject the Booking request and updates its state to REJECTED.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Carrier Booking request reference, the state of the Booking and indicating the reason for the rejection.
Carrier to Shipper
The Carrier confirms the Booking request.
The Booking is in one of the following states:
RECEIVED
UPDATE RECEIVED
CONFIRMED (if the Carrier has already confirmed the Booking but is updating its content)
The Booking is in state CONFIRMED.
The Carrier confirms the Booking request and updates its state to CONFIRMED.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Carrier Booking request reference, the Carrier Booking reference and the state of the Booking.
Carrier to Shipper
The Carrier requests that the Shipper submits an amendment to the confirmed Booking.
The Booking is in one of the following states:
CONFIRMED
PENDING AMENDMENT (if the Carrier has already requested that an amendment be submitted but is requesting additional changes)
The Booking is in state PENDING AMENDMENT.
The Carrier decides to request changes to the confirmed Booking and updates their state to PENDING AMENDMENT.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Carrier Booking reference, the state of the Booking and indicating the reason for requesting to amend the confirmed Booking.
Shipper to Carrier
The Shipper requests an amendment to the confirmed Booking.
The Booking is in one of the following states:
The original Booking is in the same state as in the preconditions. The Booking amendment is in state AMENDMENT RECEIVED.
Carrier to Shipper
The Carrier reviews the Booking amendment and decides whether the proposed changes can be confirmed.
The original Booking is in one of the following states:
The Booking amendment is in state AMENDMENT RECEIVED.
There are two possible scenarios:
The original Booking is in state CONFIRMED.
The Booking amendment is in state AMENDMENT CONFIRMED.
The original Booking is in the same state as in the preconditions.
The Booking amendment is in state AMENDMENT DECLINED.
-The Carrier performs an initial synchronous processing of the request to amend the confirmed Booking. Whether or not the Carrier will accept the proposed changes, the Carrier can accept or reject the request itself following the exception flow described in the section Carrier exception handling
There are two possible scenarios:
The Carrier confirms the requested Booking amendment and fully and permanently replaces the original Booking with it.
The Carrier updates the state of the original Booking to CONFIRMED and the state of the Booking amendment to AMENDMENT CONFIRMED.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Carrier Booking reference, the state of the original Booking and of the Booking amendment.
The Carrier declines the requested Booking amendment and updates its state to AMENDMENT DECLINED. The original Booking remains in place with its state and content unchanged.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Carrier Booking reference, the state of the original Booking and of the Booking amendment, indicating the reason for declining the amendment.
Shipper to Carrier
The Shipper cancels the amendment to the confirmed Booking.
The original Booking is in one of the following states:
CONFIRMED
PENDING AMENDMENT (if the Carrier has requested that the Shipper submits the amendment)
The Booking amendment is in state AMENDMENT RECEIVED.
The original Booking is in the same state as in the preconditions.
The Booking amendment is in state AMENDMENT CANCELLED.
The Shipper cancels the amendment to the confirmed Booking.
The Carrier performs an initial synchronous processing of the request to cancel the Booking amendment. The Carrier can accept or reject the request itself following the exception flow described in the section Carrier exception handling.
The Carrier keeps the original Booking unchanged (including its state) and cancels the Booking amendment, setting its state to AMENDMENT CANCELLED.
The Carrier responds synchronously with a successful HTTP status code.
The Carrier sends asynchronously a lightweight notification to the relevant registered counterparts containing the Carrier Booking reference, the state of the original Booking and of the Booking amendment.
Carrier to Shipper
The Carrier declines the Booking after it was confirmed.
The Booking is in one of the following states:
CONFIRMED
PENDING AMENDMENT
If a Booking amendment exists, it is in one of the following states:
AMENDMENT RECEIVED
AMENDMENT CONFIRMED
AMENDMENT DECLINED
AMENDMENT CANCELLED
The Booking is in state DECLINED.
If a Booking amendment exists, it is in state AMENDMENT DECLINED.
The Carrier decides to decline the Booking and updates its state to DECLINED. If a Booking amendment exists, it is declined along with the original Booking and the Carrier updates its state to AMENDMENT DECLINED.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Carrier Booking reference, the state of the Booking and of the Booking amendment, when applicable, indicating the reason for declining it.
Shipper to Carrier
The Shipper cancels the Booking.
The Booking is in one of the following states:
RECEIVED
PENDING UPDATE
UPDATE RECEIVED
CONFIRMED
PENDING AMENDMENT
If a Booking amendment exists, it is in one of the following states:
AMENDMENT RECEIVED
AMENDMENT CONFIRMED
AMENDMENT DECLINED
AMENDMENT CANCELLED
The Booking is in state CANCELLED.
If a Booking amendment exists, it is in state AMENDMENT CANCELLED.
The Shipper cancels the Booking. If a Booking amendment exists, it is cancelled along with the original Booking.
The Carrier performs an initial synchronous processing of the request to cancel the Booking. The Carrier can accept or reject the request itself following the exception flow described in the section Carrier exception handling
The Carrier responds synchronously with a successful HTTP status code.
The Carrier sends asynchronously a lightweight notification to the relevant registered counterparts containing the Carrier Booking request reference and/or the Carrier Booking reference, the state of the Booking and of the Booking amendment, when applicable.
Carrier to Shipper
The Carrier confirms the Booking is completed after the Transport Document has been surrendered for delivery.
The Booking is in state CONFIRMED.
The Transport Document is in state SURRENDERED FOR DELIVERY.
The Booking is in state COMPLETED.
The Carrier confirms the Booking is completed and updates its state to COMPLETED.
The Carrier sends a lightweight notification to the relevant registered counterparts, containing the Carrier Booking reference and the state of the Booking.