Understanding the Headless API Paradigm

Consuming headless APIs involves initiating requests, processing responses, and integrating received data within your systems. Unlike other API methods, headless APIs separate the presentation layer from the body. This flexible, platform-agnostic approach enables developers to consume the same backend data within a variety of custom frontends and applications.

Data flow from a database to backend tools, then to frontend tools and channels.

Benefits of Headless APIs

Liferay’s REST and GraphQL APIs follow standard protocols, simplifying integration with modern applications and external systems. Consuming these APIs involves interaction with endpoints using standard HTTP methods, calling an endpoint and managing the response the API returns.

Leveraging headless APIs to consume data

Enables loosely coupled architectures: Empower frontend and backend teams to work independently, improving scalability and maintainability.
Operates without Liferay dependencies: Integrate with any modern framework such as React, Angular, Vue, or Swift.
Facilitates precise security policies: Leverage OAuth 2.0, token-based authentication, and role-based access control.
Ensures stability: Reduce the risk of encountering breaking changes when upgrading Liferay.
Improves data retrieval performance: Create efficient experiences with pagination, filtering, and field selection capabilities.
Promotes simple debugging: Invoke methods to hit breakpoints directly while debugging.

Liferay offers both internal and headless APIs. Internal APIs, including out-of-the-box services and custom service builder APIs, tightly integrate with the platform's core architecture. Therefore, extending them requires expertise in Liferay's frameworks, OSGi, and Java.

Key differences to consider:

Versioning: Internal APIs lack versioning, unlike headless APIs.
SaaS Compatibility: Internal APIs are inaccessible in SaaS deployments due to disabled Groovy scripts, while headless APIs are fully compatible.
Complexity: Internal API development requires deep Liferay framework knowledge.

Due to these limitations, headless APIs provide greater long-term stability, easier maintenance, and increased flexibility, making them the preferred choice for most use cases.

Simplifying API Interactions with External Reference Codes

Many of Liferay’s headless APIs support External Reference Codes (ERCs), further simplifying API consumption. These ERCs provide a dual referencing capability, empowering you to fetch, update, or delete entries using either its autogenerated out-of-the-box ID or through a definable ERC. When leveraging ERCs, it’s essential to adhere to these best practices:

Ensure Uniqueness: To avoid duplicate entries, make each ERC unique within its company (Liferay instance) or site.
Avoid Reserved Characters: Properly encode ERC URL special characters for successful API calls.
Implement Lazy Referencing: Assign ERCs to related objects in separate environments to establish relationships without relying on hard-coded IDs. For example, set the same ERC for a blog post in staging and production environments to maintain consistency.
Integrate Strategically: Align ERCs with unique IDs in external systems to simplify data mapping and synchronization.

Clarity’s API-Driven Approach

Adopting an API-first strategy empowers organizations to create modern systems with seamless internal and external service integration. Clarity ensures a scalable, maintainable, and future-proof platform by prioritizing API consumption from the start within their applications. This proactive approach streamlines development and fosters a more agile and interconnected ecosystem ready for evolving business needs. Clarity can embrace headless APIs to develop modern dashboards leveraging custom object APIs and seamlessly synchronize data within external systems.

To enforce secure API access, Clarity can create service access policies controlling remote access to web services, ensuring only permitted methods are invoked by restricting access to approved entities. Further, they’ll configure an OAuth 2.0 security flow for document data requests. By designing the system to consume APIs securely from the outset, Clarity ensures operational control over how external services integrate with their platform.

For further details on enforcing secure API access, refer to official documentation (see Using OAuth 2.0) or take Foundations of Liferay's Headless API for a holistic overview.

Conclusion

Consuming headless APIs enables you to deliver consistent backend data to any custom frontend, from mobile applications to web portals. Leveraging these APIs provides loosely coupled architectures, efficient data retrieval, and secure interactions with role-based access control. ERCs provide an additional level of simplicity, establishing relationships to entries between environments without relying on hard-coded IDs.

Next, you’ll learn about interacting with Liferay’s headless APIs through REST and GraphQL endpoints.