Embedded Entity

_{Published: 20 August 2023}

Known Uses

This pattern is frequently used, especially in cases where the information is needed by consumers immediately. It reduces the number of requests and improves user experience.

Discussion Input

The design dilemma between providing Embedded Entities or Linked Information Holders is also known as the discussion between “eager loading” versus “lazy loading”. Eager loading loads all the data upfront in a single query (Embedded Entity), while lazy loading fetches related data on-demand when it’s needed (Linked Information Holder). Both approaches have their benefit: lazy loading can avoid loading unused data and eager loading minimizes the trips to the database.

In some cases, when the consumer needs all resources straight away, it is more efficient to fetch the nested resources all at once (eager loading). In a RESTful approach, this should not be the default behavior, we think. Therefore, applying this mechanism should be an explicit choice. The decision is thus left to the API consumers since they know at which moments they need additional information and precisely what that information is. In short, a resource can support “eager loading” (in addition to the default “lazy loading”), in which case the consumer can indicate that related data should be loaded along with the main resource.

The power of RESTful APIs truly comes to the forefront when the calling party can exercise significant control over the information they want to receive, and the delivering source provides information that assists the calling party in exercising that control.

In the Dutch Energy sector, we make use of the _expand parameter for enabling eager loading of Linked Information Holders (becoming an Embedded Entity when it is expanded, aka “resource expansion”) and the _fields parameter to select fields or combination of fields in the response explicitly (which can be seen as a realization of the Wish List pattern). Using these parameters, the client controls the information retrieval and can avoid unnecessary data transfer.

Now back to the design dilemma of embedding data elements vs providing links. When comparing the response on page 317 and page 323 in the book (customerProfile as Embedded Entity or Linked Information Holder) we would have decided for modelling customerProfile as an Embedded Entity and not as a Linked Information Holder. The reason for this design decision is that the customerProfile Embedded Entity can be seen as a composite attribute, clustered group of data elements or data group without an identifier (aka value objects), which is something else than an associated resource that can be identified by MRID Master Resource IDentifier (aka entities). In our design strategy, data groups are never accessible via a link; they only exist within the context of the owning API, whereas related resources can exist outside the context of the owning API, possibly by an alternative API. The _fields parameter can be applied to data elements or groups of data elements, and the _expand parameter to related resources referenced by links to reduce messages size, support eager loading, and allow clients to select the information they are interested in.

An example of a related resource provided in the book is the “policies” related resource collection (page 121):

curl -X GET http://localhost:8090/customers/rgpp0wkpec
{
  "customerId": "rgpp0wkpec",
  ...
  "_links": {
  ...
    "policies": {
      "href": "/customers/rgpp0wkpec/policies"
    }
  }
}

In Dutch Energy sector design strategy, resources are defined as top-level resource, subresource, associated resource, and resource reference. They can be referenced by links and/or be fully embedded in the response via the _expand parameter. A group of elements can be explicitly embedded in the response via the _fields parameter. So:

curl -X GET http://localhost:8080/customers/gktlipwhjr?_fields=customerProfile would only return the customerProfile data group:

{
  "customerProfile": {
    "firstname": "Robbie",
    "lastname": "Davenhall",
    "birthday": "1961-08-11T23:00:00.000+0000",
    "currentAddress": {
       "streetAddress": "1 Dunning Trail",
       "postalCode": "9511",
       "city": "Banga"
    }
  }
}

In summary it’s an essential design choice to decide between Embedded Entities and Linked Information Holders, each of them having their own mechanism in constructing the needed response shape.

Known Uses

Discussion Input

Recommended Reading

Leave a Reply Cancel reply