Querying Related Data

Efficiently managing and retrieving related data is crucial for building responsive applications with Liferay. Liferay provides two powerful strategies for querying related entries: relationship endpoints and the nestedFields parameter. Each method offers unique advantages, and understanding the trade-offs between these approaches is essential to delivering seamless user experiences while balancing performance and usability.

This article explores how to query and manage related data in Liferay using relationship endpoints and the nestedFields parameter.

Understanding Relationship Endpoints

You can add relationships between Liferay objects to link their entities. When relationships are created between objects, Liferay generates these REST endpoints for accessing the relationship tables:

• GET: Returns related object entries.
• PUT: Relates object entries.
• DELETE: Disassociates related object entries.

Endpoints are added to the parent object in one-to-many relationships and to both objects in many-to-many relationships. When inheritance is enabled for root objects, all relationship endpoints are consolidated within the parent object's APIs.

See Using Relationship REST APIs for a full list of generated relationship APIs.

Strategies for Consuming Relationship Endpoints

When using relationship endpoints to query related entries, a single API call retrieves a list of all entries related to the current entry using the specified relationship. This focused scope provides these benefits:

• Granular Control: Minimize unnecessary data fetching by retrieving only the data you need.
• Reduced Payload Size: When loading data in response to user interactions, keep API responses lean and reduce network load.
• Lower Initial Database Load: Fetch fewer relationships to simplify and focus individual database queries.

However, in some situations you may need more information than what relationship endpoints provide. For example, you might need the primary object as well as related entries from multiple relationships. This requires additional API calls, which can introduce these drawbacks:

• Increased Latency: Multiple API calls can increase latency due to network round-trips, potentially slowing performance, especially with many related objects.
• Increased Overhead: Frequent server communication can increase the number of requests, impacting server and client performance, particularly with many objects.

Understanding Nested Fields

In addition to relationship endpoints, Liferay provides the nestedFields parameter, which you can use to return multiple levels of related entries in a single GET request. When using nested fields, you enter the names of the relationships you want to include, separating each relationship with a comma (e.g., nestedFields=[firstObjectRelationship],[secondObjectRelationship]). If the relationships span multiple levels, set the nestedFieldsDepth parameter to the depth you need. You can include up to five levels (e.g., nestedFieldsDepth=5).

Strategies for Consuming Nested Fields

When using nestedFields to query related entries, a single API call retrieves both the primary entry and its related entries using the specified relationships. This comprehensive approach provides these benefits:

• Single API Call: Reduce network latency and simplify frontend/backend interactions by retrieving all necessary data in a single request.
• Optimized Rich Data Views: Build optimized, rich data views that include all necessary related information in a single API call (e.g., a detailed ticket view).
• Enhanced User Experience: Deliver a seamless and responsive user experience by making all related data instantly available without requiring additional clicks or loading screens.

However, comprehensive data retrieval is not recommended for all use cases. For example, your solution might only require some related data upfront and load additional data via user interactions. In this case, retrieving all information at once can have these drawbacks:

• Complex Queries: Using nested fields increases the complexity of the database query. While this is often more performant than multiple API calls, it adds strain to the database.
• Payload Bloat: Retrieving too many nested fields can lead to large payloads. This increases the amount of data transferred and may negatively impact page load times if the information isn’t used immediately.
• Unnecessary Data Fetching: Fetching unnecessary data can decrease efficiency. If you don't need some related data immediately, loading it in advance with the initial API call can be counterproductive.

Deciding Which Strategy to Use

When working with related data, deciding between relationship endpoints and nested fields is crucial for performance and usability. Both approaches have their place, and the key is understanding the requirements of your application.

• Use nestedFields when all data is displayed or used at once. This reduces API calls and improves performance and user experience.
• Use relationship endpoints and multiple API calls when data is revealed progressively or only upon user interaction. This reduces unnecessary data fetching.

Querying Clarity’s Related Data

Clarity wants to associate tickets with one another, so they’ve defined a one-to-many relationship ( ticketToTickets) where the Ticket object is related to itself. This generates these relationship endpoints:

Clarity can use these endpoints to quickly surface information about related tickets, facilitating efficient customer service operations. Additionally, they plan to display details from multiple related tickets in a single, unified dashboard. This dashboard should include epics, tasks, and sub-tasks connected with parent-to-child relationships. To collect related ticket data, they can leverage nestedFields with a nestedFieldsDepth of three.

Conclusion

Understanding related data management through relationship endpoints and nested fields is essential. These tools empower developers to optimize API calls based on their application's requirements, improving both performance and user experience. Relationship endpoints enable standard CRUD operations, complex queries, and management of relationships between objects. Nested fields save API calls and improve user experiences in situations where all data is displayed at once.

Next, you’ll practice consuming related data with Liferay’s headless APIs.