Available Methods for Consuming Data

With Liferay, developers have access to both REST and GraphQL headless APIs. While both offer unique advantages, deciding between which to use when consuming data involves your team’s use cases, expertise, and project-specific requirements. This lesson explores the benefits of both approaches.

Consuming REST APIs

Liferay's REST APIs are fully OpenAPI-compliant, ensuring broad compatibility with tools and libraries supporting the OpenAPI specification. As an established industry standard, REST is widely adopted for API communication. REST APIs are particularly suited for:

• Familiarity and Tooling: Developers familiar with REST can easily integrate Liferay's APIs into their workflows using tools like Postman or Swagger.
• Standard Operations: Ideal for straightforward CRUD operations (Create, Read, Update, Delete) and common integration patterns.
• Ease of Use: OpenAPI documentation provides clear guidance on structure and syntax, reducing learning curves and ensuring predictable behaviors.
• Batch Operations: With Liferay’s batch API capabilities, REST can handle large data sets effectively, making it suitable for data migrations or bulk updates.

Liferay’s REST APIs follow the principles of RESTful architecture, offering multiple HTTP methods to interact with resources. Although the methods available depend on the specific REST application and endpoint, methods commonly supported include GET, POST, PUT, PATCH, and DELETE.

Consuming GraphQL APIs

GraphQL APIs present a distinct paradigm prioritizing flexibility and efficiency. Unlike REST, which returns a fixed set of data per endpoint, GraphQL empowers developers to specify exactly what data they need in a single request. This is particularly advantageous for:

• Reducing Payloads: Retrieve only necessary fields, optimizing bandwidth for mobile applications and similar scenarios.
• Complex Queries: Query multiple entities in single requests, minimizing the number of API calls to fetch data.
• Dynamic Needs: Ideal for frequent data requirement changes, as GraphQL queries can be adapted without requiring backend modifications.

GraphQL’s ability to combine fetching and modifying operations into a single query makes it highly efficient for complex data interactions. You can use query operations to retrieve specific fields, related data, and apply filters, all in a single request. This eliminates over-fetching and under-fetching issues common with REST APIs. An example call querying Clarity’s accounts could look like:

query {
   accounts(
      filter: ""
      page: 1
      pageSize: 10
      search: ""
      sort: ""
   ) {
      items {
         id
        name
      }
   }
}

Additionally, mutation operations can create, update, or delete data. A mutation in GraphQL functions similarly to POST, PUT, or DELETE in REST, depending on the operation defined. An example mutation for Clarity creating or modifying customer data could include:

mutation {
    createAccount(account: {name:"MyCustomer"}){
        id
        name
    }
}

Deciding Between Consumption Methods

Evaluating between feature availability, flexibility, and project needs is essential when choosing between REST and GraphQL. Other factors to consider include evaluating

• Complexity vs. Familiarity: REST is easier for teams familiar with OpenAPI and requires less setup. GraphQL, while more flexible, can have a steeper learning curve and may require additional tooling.
• Data Requirements: GraphQL is beneficial when precise control over data retrieval is needed or when accessing multiple related entities in a single request. For simpler use cases, REST is often sufficient.
• Scalability and Caching: REST benefits from built-in caching at multiple layers (CDNs, proxies, and browsers), making it more efficient for high-traffic applications. GraphQL’s dynamic queries can make caching more complex but may reduce the number of requests needed.
• Project Standards: Existing development guidelines or preferred frameworks within your team or organization may guide the decision.
• Future Maintenance: REST APIs are widely supported and easier to maintain, making them a safer choice for long-term projects, especially in teams with limited GraphQL expertise.

Selecting Clarity’s API Interactions

While GraphQL allows clients to request only the fields they need, REST provides similar functionality with fields and restrictedFields parameters. However, GraphQL’s capabilities for Object APIs in Liferay have notable limitations—they don't support retrieving or updating objects using ERC, invoking Object Actions, using PATCH methods, or accessing relationship APIs.

In contrast, REST fully supports these operations, making it the preferred choice for Object-based implementations like Clarity’s planned ticketing system.

Conclusion

Liferay provides both REST and GraphQL headless APIs for consuming data. REST provides a clear and structured way to interact with Liferay resources, enabling you to choose appropriate methods depending on your requirements for consuming data. GraphQL alternately allows you to both fetch and modify data in single, flexible queries.

Next, you’ll practice setting up secure API access for Clarity’s dashboards.