Legacy Get Migration Guide
This migration guide is to prepare customers for the upcoming change in the service framework api for retrieving Cache and Data documents by key and _id, respectively.
If you're already using hyper-connect@>=0.6.0, then you don't need to worry about this; you're already using the new shape. :)
Almost all hyper service apis return a common shape, referred to in this guide as the "hyper response shape". This shape looks something like:
If ok is false, then msg and status may be provided for additional context into the error that occurred. For example, if a document is not found when Retrieving a Data Service document by _id, then a "hyper response shape" is returned with ok false and status 404.
For adapters, we encourage status to be some http status code (no point in re-inventing the wheel), but it is a convention, not a requirement
Otherwise, if ok is true, a service api response will include a field on the "hyper response". For example, when Querying a Data Service, the "hyper response" will also contain docs fields. When Querying a Search Index, the "hyper response" will also contain a matches field.
Effectively, ok is a discriminating field between a "hyper success response" and a "hyper error response"
With the hyper-connect client, similar to fetch, it will only throw if a 5xx status code is received from a request. Therefore, any other status codes, for example 4xx statuses, must be checked for by business logic. This is by design, as it forces developers to handle error cases in consumer code, without relying on their services tier to handle errors. These errors most likely have semantic meaning according to the business rules, and should be handled accordingly.
A common pattern is something like this:
The exception to this "hyper response shape" convention have been when Retrieving a Data Service document by _id and Retrieving a Cache Service value by key. Instead of always returning a "hyper response shape", these apis would return the resource directly if found, and then a "hyper error response shape" only if an error occurred ie. the document or value was not found.
This divergence from the convention leads to some unergonomic usage in consumer code:
Checking the status has similar issues, in that what if the document has a status field?
Finally, TypeScript, which has become ubiquitous in the Node/JavaScript world, is not able to reconcile this overlap, forcing developers to typecast, or using @ts-ignore to get around the errors. This makes these apis a potential source of bugs and in consumer code.
To address this, we will be changing the behavior of these two apis to return a "hyper response shape", just like all of the other apis.
For both Retrieving a Data Service document by _id and Retrieving a Cache Service value by key, the new response shape will look like this:
doc will contain the value retrieved from the service. To allow teams to migrate to this new shape, we have introduced a new header that can be used to incrementally adopt this new shape.
The X-HYPER-LEGACY-GETheader can be used to tell your hyper service whether to return the new "hyper response shape" or the legacy shape.
If set to true, your hyper service will return the legacy shape. If set to false , your hyper service will return the "hyper response shape".
This header can be used by consumers to allow incremental migration to the new shape, in a multi-phase approach.
Right now, by default, your hyper service will return the legacy shape, if the header is not provided.
This allows for teams to optionally set the X-HYPER-LEGACY-GET header to true when they are ready to adopt the new shape.
In a future major release, we will make a breaking change to default to the "hyper response shape", if the header is not provided
If your team is still not ready to use the new shape, you should explicitly set X-HYPER-LEGACY-GET to true to continue receiving the legacy shape
In another future major release, we will remove the X-HYPER-LEGACY-GET header entirely, thus removing the legacy shape from the hyper service apis.
We made a breaking change in hyper-connect@v0.6.0 to automatically set the X-HYPER-LEGACY-GET header to true. This is an easy way to adopt the new shape: bump your version and let TypeScript or your editor tell you where to make the updates.
We are changing Retrieving a Data Service document by _id and Retrieving a Cache Service value by key to return the following shape, instead of the document directly:
Bump your hyper-connect version to 0.6.0 and start consuming the new shape: