Portbase Tracking API

This API can be used to receive **real-time** updates about the voyages, visits and (detached) handlings. To achieve these real-time updates the API uses a mechanism called 'long polling'. When you send a request to listen for updates, you will receive an update immediately when it happened since your last request. Or when there is no update, it will wait until there is, or timeout when the maxTimeout you specified is reached. After the api response has returned, and your client has finished processing the updates, you should always update your position. This way the next time you ask for updates, the API will look for updates after that position in the event log. This mechanism also enables batching, since you will receive all updates as fast as you can process them. Important to realize is that you will receive updates with a _before_ and _after_ situation in which only the changes are incorporated. So when only one handling is changed, you will receive only that handling within the visit within the voyage and not all containers and visits! The same per-item delta applies to the `trainLocationReports` on a rail voyage: each update contains only the reports that were added or changed, not the reports you already received in earlier updates. ## Usage Using the Tracking API should be a continuous process, running 24/7, looping through the following sequence of API calls 1. Call `/listen` 2. Process the updates that were returned 3. Immediately after 2., call `/updatePosition` when done with your updates (even if the `/listen` response was empty, the index was null etc.) 4. Keep repeating step 1-3 5. When your process needs to stop, restart or redeploy, call `/disconnectClient` **Important:** - Implement this as a continuous loop where `/listen` is called immediately after `/updatePosition`. Do not use scheduled tasks (cron jobs), as this causes updates to accumulate faster than they can be processed, preventing real-time tracking. - Keep the timeout as high as possible (we recommend the default of 95000 ms). Results are returned immediately when available, but a higher timeout reduces connection overhead when updates are less frequent. Disconnecting the client makes sure that other connecting clients will receive the updates that were meant for this client. That is because you can connect multiple clients and each client is assigned a segment (range). Updates for a voyage will always be handled by the same segment. So when you do not disconnect your client, the other connected clients will not receive the updates for your segment(s) for a while. After a while when a client does not ask for updates, those segments are released to the other client(s). ## Things to consider when receiving updates In some situations you may receive multiple updates for one logical change. This happens when the change involves two voyages or a voyage and a detached handling. The order in which the updates for the different entities are received is not guaranteed. This may pose a challenge, depending on the structure of the data model used on the client side. The following sections describe the situations where this can occur and how to mitigate challenges caused by out-of-order updates. ### 1. A handling was attached Attaching a detached handling to a visit or voyage will result in two updates: - The detached handling will be marked as attached (`attached=true`) - The handling will appear as a new item in the array of handlings of the visit. If your data model only has a single copy of a handling (i.e. it does not store attached and detached handlings separately), then ignore the update of the detached handling and only process the update of the visit the handling was attached to. Subsequent updates of the handling will appear on the now attached handling on the visit. ### 2. A handling was detached Detaching a handling from a visit or voyage will result in two updates: - The handling will be marked as detached (`attached=false`) - The handling will disappear from the array of handlings of the visit it was attached to. If your data model only has a single copy of a handling (i.e. it does not store attached and detached handlings separately), then ignore the update of the visit the handling was detached from and only process the update/creation of the detached handling. Subsequent updates of the handling will appear on the now detached handling. ### 3. A handling was moved Moving a handling from one visit to another visit in a different voyage will result in two updates: - The handling will disappear from the array of handlings of the visit it was previously attached to. - The handling will appear as a new item in the array of handlings of the visit it's moved to As mentioned earlier, these updates may be received out-of-order. If your data model only has a single copy of a handling (i.e. it does not store a copy per visit it is attached to) then the handling may end up in the wrong state (not attached to any visit). To prevent this: - Ignore updates where a handling is removed from a visit it is not attached to according to your data model. - Process updates where a handling is attached to a visit, even though the handling is attached to another visit according to your data model Subsequent updates of the handling will appear on the visit it was moved to. ### 4. A visit was moved This scenario is almost identical to the previous one, where a handling was moved to a visit of another voyage. The difference is that in this case the voyage data is changed, such as the transportation vehicle, instead of the visit data. The challenges in this scenario are also similar and the same strategies to mitigate them should be followed. Subsequent updates of handlings will appear on the voyage the visit was moved to.