Many resources in the Flexport API contain attributes that are references to another resource or a collection of resources. For example, a shipment has a reference to a collection of legs. Expansion can be used to replace those references with the actual data that they represent. This is helpful in eliminating subsequent calls required to retrieve all data relevant to a resource.
Expansion is controlled via the expand query parameter. Multiple references can be expanded by providing multiple items in the expansion array. Expansion may also be recursive, i.e. expanded references can be further expanded.
Expansion is valid for both ObjectRef and CollectionRef attributes.
Here are some different ways that the expand query parameter can be used with the Container API. In the JSON
examples, some attributes are removed for brevity and replaced with ...
curl -X GET \
https://api.flexport.com/ocean/shipment_containers/123
{
"_object": "/api/response",
"self": "https://api.flexport.com/ocean/shipment_containers/123",
"version": 2,
"data": {
"_object": "/ocean/shipment_container",
"id": 123,
...
"shipment": {
"_object": "/api/refs/object",
"ref_type": "/shipment",
"link": "https://api.flexport.com/shipments/222",
"id": 222
},
"container_legs": {
"_object": "/api/refs/collection",
"ref_type": "/ocean/shipment_container_leg",
"link": "https://api.flexport.com/ocean/shipment_container_legs?f.shipment_container.id=123"
},
...
}
}
expand=container_legsThe container_legs attribute will be expanded into a JSON array of ContainerLeg objects, instead of the
normal behavior of the legs attribute being a single CollectionRef<ContainerLeg>
curl -X GET \
https://api.flexport.com/ocean/shipment_containers/123?expand=container_legs
{
"_object": "/api/response",
"self": "https://api.flexport.com/ocean/shipment_containers/123",
"version": 2,
"data": {
"_object": "/ocean/shipment_container",
"id": 123,
...
"shipment": {
"_object": "/api/refs/object",
"ref_type": "/shipment",
"link": "https://api.flexport.com/shipments/222",
"id": 222
},
"container_legs": {
"_object": "/api/collections/paginated",
"prev": null,
"next": null,
"total_count": 1,
"data": [
{
"_object": "/ocean/shipment_container_leg",
"id": 11111,
"dates": {},
"shipment_container": {
"_object": "/api/refs/object",
"ref_type": "/ocean/shipment_container",
"link": "https://api.flexport.com/ocean/shipment_containers/289140",
"id": 289140
},
"leg": {
"_object": "/api/refs/object",
"ref_type": "/shipment_leg",
"link": "https://api.flexport.com/shipment_legs/4501396",
"id": 4501396
}
}
]
},
...
}
}
expand=container_legs.legEach ContainerLeg object itself contains an ObjectRef<ShipmentLeg>, and the expand syntax can be chained to
expand both the countainer_legs array, and each leg within each ContainerLeg
curl -X GET \
https://api.flexport.com/ocean/shipment_containers/123?expand=container_legs.leg
{
"_object": "/api/response",
"self": "https://api.flexport.com/ocean/shipment_containers/1234",
"version": 2,
"data": {
"_object": "/ocean/shipment_container",
"id": 1234,
...
"shipment": {
"_object": "/api/refs/object",
"ref_type": "/shipment",
"link": "https://api.flexport.com/shipments/123",
"id": 123
},
"container_legs": {
"_object": "/api/collections/paginated",
"prev": null,
"next": null,
"total_count": 1,
"data": [
{
"_object": "/ocean/shipment_container_leg",
"id": 11111,
"dates": {},
"shipment_container": {
"_object": "/api/refs/object",
"ref_type": "/ocean/shipment_container",
"link": "https://api.flexport.com/ocean/shipment_containers/289140",
"id": 289140
},
"leg": {
"_object": "/shipment_leg",
"id": 4501396,
"estimated_arrival_date": "2019-05-1T12:00:00.000+08:00",
"actual_arrival_date": "2019-05-1T21:52:00.000+08:00"
...
}
}
]
},
...
}
}
expand=shipment.ocean_shipment.containersExpand out the shipment attribute to get a Shipment object instead of a ObjectRef<Shipment> object. Then, a
Shipment object contains an OceanShipmentDetail. The OceanShipmentDetail is not stored as a ref within the
Shipment object, so the full OceanShipmentDetail object will be returned and does not need to be expanded.
However, each OceanShipmentDetail object contains a CollectionRef<Container>, and with this syntax that array
of containers will be expanded out.
You could use this expansion if you had the id of a container, and wanted to know all the other containers
that are on the same shipment.
curl -X GET \
https://api.flexport.com/ocean/shipment_containers/123?expand=shipment.ocean_shipment.containers
{
"_object": "/api/response",
"self": "https://api.flexport.com/ocean/shipment_containers/123",
"version": 2,
"data": {
"_object123 "/ocean/shipment_container",
"id": 123,
...
"shipment": {
"_object": "/shipment",
"id": 222,
"transportation_mode": "ocean",
...
"ocean_shipment": {
"_object": "/ocean/shipment",
...
"containers": {
"_object": "/api/collections/paginated",
"prev": null,
"next": null,
"total_count": 1,
"data": [
{
"_object": "/ocean/shipment_container",
"container_type": "dry",
...
}
]
}
}
}
"container_legs": {
"_object": "/api/refs/collection",
"ref_type": "/ocean/shipment_container_leg",
"link": "https://api.flexport.com/ocean/shipment_container_legs?f.shipment_container.id=123"
},
...
}
}
expand=container_legs.leg,shipment.ocean_shipment.containersMultiple expansion paths can be passed to the expand query parameter.
curl -X GET \
https://api.flexport.com/ocean/shipment_containers/123?expand=container_legs.leg,shipment.ocean_shipment.containers
{
"_object": "/api/response",
"self": "https://api.flexport.com/ocean/shipment_containers/123",
"version": 2,
"data": {
"_object123 "/ocean/shipment_container",
"id": 123,
...
"shipment": {
"_object": "/shipment",
"id": 222,
"transportation_mode": "ocean",
...
"ocean_shipment": {
"_object": "/ocean/shipment",
...
"containers": {
"_object": "/api/collections/paginated",
"prev": null,
"next": null,
"total_count": 1,
"data": [
{
"_object": "/ocean/shipment_container",
"container_type": "dry",
...
}
]
}
}
}
"container_legs": {
"_object": "/api/collections/paginated",
"prev": null,
"next": null,
"total_count": 1,
"data": [
{
"_object": "/ocean/shipment_container_leg",
"id": 11111,
"dates": {},
"shipment_container": {
"_object": "/api/refs/object",
"ref_type": "/ocean/shipment_container",
"link": "https://api.flexport.com/ocean/shipment_containers/289140",
"id": 289140
},
"leg": {
"_object": "/shipment_leg",
"id": 4501396,
"estimated_arrival_date": "2019-05-1T12:00:00.000+08:00",
"actual_arrival_date": "2019-05-1T21:52:00.000+08:00"
...
}
}
]
},
...
}
}