API – Nested Entities
Nested entities are entities that are either inside of or connected to another entity. By default, nested entities are not returned to save on bandwidth and to avoid infinite loops (entity relationships can be cyclical). To help understand nested entities, an image is presented below.
In the above image, each box represents an entity. Boxes can be nested inside of other boxes; each nesting shows the nested entities of that entity. The red line shows a relationship between loans and customers. Customers can be referenced through a loan and loans can be referenced through a customer. This relationship is shown through a nested entity since OData does not distinguish between entities being contained and entities being referenced. This means that from an integration's perspective, referenced entities and contained entities are the same. Consequently, the LoanPro documentation will refer to both cases as "nested entities".
Nested entities exist primarily for two reasons a) performance and b) representing relationships. Since nested entities are not delivered by default, it lowers the amount of bandwidth used and lowers the amount of time the server spends preparing the response. The other main reason for nested entities is it allows the API to represent entity relationships. With traditional REST APIs, related entities are either returned by default, which increases bandwidth usage, or require querying additional endpoints, which slows down processes as there need to be multiple round-trip requests. For these reasons, OData and LoanPro both use nested entities for related entities.