The Round Trip Problem
Consider a new feature added to the Product API version 1.1.0. For example, version 1.1.0 may add a property
Thus, the corresponding
UpdateProduct classes in the SDK for API version 1.1.0 will also define
Apiture Digital Banking APIs account for clients that are still using the older SDK for Product API 1.0.0, even though the
API is now running 1.1.0.
The TypeScript SDK for the Product API 1.0.0 includes TypeScript classes for 1.0.0 which do not include
If the client receives an
or is passed a JSON representation of a
product instance, it will contain the new property:
"..." : " ... other properties ..."
When the client (via the SDK) marshals that JSON into a
Product 1.0.0 object,
guaranteeType property is dropped because the
Product class has has no such property.
The same would happen in other client programming languages, such as a class named
Product in a Java SDK.
If the client modifies the representation, then submits a
PUT request, the reverse object mapping occurs: the client
must convert the
UpdateProduct object to JSON. However, when using SDK 1.0.0,
UpdateProduct class and schema will not contain
guaranteeType property. Without version information in the request, a
PUT update will change the persisted value of the
property for that product instance from
null. (This is the defined behavior of
PUT is always a complete
replacement of the resource representation.) In the absence of any version information in the request,
guaranteeType is not present in the request, the server would not know the difference
between an older 1.0.0 client invoking the
and a 1.1.0 client attempting to remove the value of
it would change the persistent value of
This is the Round Trip Problem with
This round trip problem only occurs for clients which map JSON to strongly typed objects (programming languages objects,
not JSON objects), manipulate the objects, and then map objects back to JSON. Round tripping is not an issue when
clients operate on JSON objects directly instead of marshaling the JSON into and out of native objects. In this case,
guaranteeType property remains in the client’s JSON object and is returned in the
PUT request body, even though the
client is unaware of it.
PATCH operations do not have
this round trip problem, as values that are omitted from the
PATCH request body are
ignored and do not change the value on the server.
That is, the behavior of
PATCH works whether
guaranteeType was intentionally omitted in the request body, or because
the 1.0.0 SDK does not have a corresponding property.
To solve this when using the SDK or marshaling, the Apiture Digital Banking API SDK does the following two operations:
- The SDK injects the correct
_profilein the representation. The
_profileURL includes to the resource version associated with API version for that SDK - i.e. it identifies the
Productinstance version as 1.0.0. If
_profilewas omitted, the resource would is interpreted as version 1.1.0 of the Product schema, and the
PUTrequest would clear out the value of
guaranteeTyperather than leave it unmodified. The SDK constructs the new request body with an accurate
_profilevalue associated with the SDK version, and thus it does not round-trip the
_profilein the input.
- The SDK for Product 1.0.0 passes the
Apiture-Version: 1.0.0header in the request.
- The SDK passes the API key request header; this value is also a surrogate for the
If a client does not use the SDK, it should account for the round trip problem in the same way: include the
that reflects the expected version number of the resource, and pass the correct
Apiture-Version header corresponding
to the schema version associated with the resource and the client’s API key.