Available Custom Shapes

As and when new features are added to this REST API, backward compatibility of existing interfaces is a key consideration. It is usual practice that adding new optional content isn't a breaking change. However, when content is relocated or removed entirely, this is likely to be a breaking change. To avoid this breakage, changes to existing resource structures will be implemented as "custom shapes". That is, multiple structures can exist for the same underlying resource type, although each will use a different root resource name.

These representations can co-exist indefinitely if required, although in many cases it's expected that the new structure will become the preference and so a way to set this as the "default" structure is available. This is achieved by configuring a "default shape" property:

glog.fusion.cil.config.defaultShape.<version>.<resource name> = <custom name>

For example, to make the custom shape "abcd" the default shape for the shipments resource name, set the following:

glog.fusion.cil.config.defaultShape.v2.shipments = abcd

The available shapes are described below.

Enhanced Shipment Ship Unit Support

The current shipments resource contains shipment ship unit information in a read-only capacity. In addition, the content appears within the shipment stop detail and in a redundant manner i.e. the same ship unit information appears multiple times; once for pick up stop and once for drop off stop.

Starting in 24A, the ship unit information will appear once as an immediate child resource of the shipment and will not appear under each stop detail. This structure will also support create and update of shipment ship units as part of the shipment create and/or update.

This structure is expected to be the preferred structure and so has been implemented as the default resource structure for the shipments resource for all new customers. However, for existing customers who use the original structure, they will continue to see the original structure when the shipments resource name is used.

This has been achieved by defining a custom shape call shipmentNoSSUs which correlates to the original structure, and staging a default shape property in the CUSTOM property set so that requests for the shipments resource will correspond to the shipmentNoSSUs shape. This preserves backward compatibility.

glog.fusion.cil.config.defaultShape.v2.shipments = shipmentNoSSUs

After evaluation of the new shape (on a test system), changing to use the new shape as the default can be achieved simply by removing the above property definition from the CUSTOM property set.