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. :)
Some Background
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 Problem
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.
A hyper Response shape
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.
Migration Path
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.
First Phase: On By Default
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.
Second Phase: Off By Default
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
Third Phase: Remove the Header
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.
hyper-connect breaking change
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.
TL;DR
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:
ο»Ώ