Developing Custom Service APIs

To unlock the full potential of Liferay DXP, developing tailored APIs is essential. While Liferay Objects APIs offer a no-code method for exposing custom data, some complex scenarios may require custom-built APIs for intricate functionalities. Although traditional approaches like JAX-RS development are available, they can be time-intensive and require extensive coding. REST Builder addresses this challenge by significantly reducing development time and effort through automated code generation.

REST Builder provides a streamlined, Liferay-centric approach to creating RESTful services that integrate seamlessly with the platform's features. This enables developers to exercise fine-grained control over the API endpoints they build and deploy. Such control is crucial in scenarios where standard CRUD operations are insufficient, such as integrating with complex external systems or implementing custom workflows.

Understanding REST Builder Implementations

REST Builder development centers around two configuration files: rest-config.yaml and rest-openapi.yaml. These files determine your API's structure and behavior. Once defined, you can execute a Gradle task within your Liferay workspace to generate a significant portion of your API's required code. This generated code includes interfaces, resource classes, and other essential scaffolding. It also generates packages containing GraphQL endpoints, JAX-RS application code, and a resource package with your API implementation code.

Before setting up REST Builder projects, it's essential to grasp additional concepts and prerequisites for successful implementations.

Preparing with Service Builder

Optimal API development using REST Builder begins with creating a corresponding Service Builder (SB) module. This establishes a foundation for managing entity permissions within Liferay's framework and provides structure for defining business logic, default permissions, and remote service methods.

When constructing SB modules for REST Builder APIs, adhere to these implementation steps and best practices:

• Database Persistence: Define and persist entities in the database using Liferay's Service Builder tool, configuring column types and relationships according to RDBMS best practices. See Service Builder for more information on creating SB modules.
• Default Permissions: Specify default entity permissions in resources/actions/default.xml, ensuring proper access based on roles (RBAC).
• Remote Service Implementation: Configure service.xml to generate local and remote services, incorporating permission checks in remote service methods using PermissionChecker.
• REST Builder Integration: Use SB remote service methods within your REST Builder resource implementations, leveraging the effective user for permission checks when invoking remote SB services.

With your database framework in place, you can begin your API implementation.

Advantages of REST Builder

Java API developers often turn to JAX-RS for creating RESTful services. However, Liferay's REST Builder offers distinct advantages within the Liferay ecosystem.

• Automatic Framework Generation: REST Builder generates many elements you'd need to manually configure with JAX-RS, such as annotations, converters, multipart support, and code structuring. By enforcing OpenAPI specifications, REST Builder ensures a consistent look and feel across all APIs, enhancing maintainability.
• Streamlined Testing: Built-in templates simplify API unit and integration testing.
• Liferay Integration: REST Builder leverages Liferay's built-in authentication, CORS handling, and headless capabilities for search, filtering, and paging.

While JAX-RS remains a viable option for specific business needs, REST Builder is often a better fit for Liferay development.

Best Practices for REST Builder Development

A well-defined plan for schema denormalization and API versioning is vital for successful REST Builder projects.

Schema Definitions and Denormalization

Denormalized schemas enhance performance for REST endpoints, enabling consumers to receive complete objects in a single request. Consider these essential schema definition practices:

• SB Normalization, REST Denormalization: While SB entities should remain normalized for RDBMS integrity, the REST implementation should merge related entities into a single response object.
• Avoid Overly Granular Endpoints: Instead of creating a dedicated API to fetch a single attribute (e.g., date of birth), return the entire object and allow consumers to filter fields via Liferay's built-in field selection support.
• Optimize Large Objects: If a resource contains extensive data, provide query parameters to limit the returned fields where necessary.

API Versioning

API versioning is necessary to ensure backward compatibility and smooth transitions for consumers. Consider these principles when determining whether versioning is appropriate:

• Path Changes: Introduce a new version when modifying URL structures.
• Schema Modifications: Version when removing or changing fields in existing responses.
• Optional Additions: When adding new optional fields that don't impact existing consumers, assess whether versioning is necessary.

Equally important is avoiding unnecessary versioning. Minimize breaking changes by designing APIs with forward compatibility in mind, and implement shims for legacy versions to transform responses to match newer versions when feasible. When possible, continue to support legacy API versions to avoid forcing consumers to immediately upgrade.

Conclusion

Developing efficient custom service APIs requires a solid understanding of REST Builder and well-defined implementation plan. Service Builder modules establish the foundational structure for business logic, permissions, and remote service methods. REST Builder then automates the generation of essential API project elements, significantly reducing development time and ensuring robust, consistent, and well-integrated APIs.

Next, you'll learn more about setting up REST Builder projects.