REST API Integration of a Carrier Platform with Lobster Data

Operational Starting Point

This integration started in a common legacy context: a stable tour management system in daily production, but without the payload shape required by an external carrier platform. As soon as order updates, status changes, or dispatch events had to be transferred, manual correction loops appeared in the process. That created avoidable waiting time and increased failure probability in downstream steps.

The issue became more visible under load. During short bursts of outgoing orders, even small semantic mismatches produced return errors and manual rework. The goal was therefore not just to connect two systems, but to establish a robust exchange model that remains predictable in day-to-day operations.

Technical Context

The core implementation used Lobster Data with an HTTP API connector as a dedicated transformation and control layer. In this setup, Lobster Data handles more than field mapping: input validation, structure normalization, business-rule application, send orchestration, and traceable error feedback.

This approach keeps the source system untouched while still enforcing a strict target-side JSON contract. Instead of embedding new API semantics into the legacy core, integration logic remains versionable in middleware and can be changed in small, reversible increments.

Structure Build: The Array Problem

A critical reliability issue involved list fields such as stops or references. Some source payloads serialize a single item as an object instead of an array. Humans can read both variants, but strict API validation often rejects the object variant as structurally invalid.

This is the classic Max=1 semantic mismatch: business-wise, one element is valid, but technically the API still requires a list. The fix is a deterministic normalization step before validation and send, so all affected fields are converted to a canonical array representation.

                {
  "shipmentId": "4711",
  "stops": {
    "stopId": "123",
    "type": "pickup"
  }
}
              

                {
  "shipmentId": "4711",
  "stops": [
    {
      "stopId": "123",
      "type": "pickup"
    }
  ]
}
              

Error Classification and Triage

The live profile uses three explicit error classes: transport errors, validation errors, and process errors. Each class follows a different response path with different urgency and ownership.

This separation is operationally important. Transport failures require availability and retry handling, validation failures require record correction or mapping refinement, and process failures often require business-side clarification. The result is faster triage and fewer unnecessary escalations.

Pattern Reusability

The same model applies to many legacy-to-platform integrations: keep the core system stable, enforce explicit mapping contracts in middleware, normalize structures deterministically, and run a clear operational failure model.

Conclusion

The integration succeeded because it delivered both technical correctness and operational control. The legacy system remained stable, the carrier platform received consistent payloads, and incidents became easier to classify and resolve.