Exploring Liferay’s APIs

Proactively exploring and understanding available headless APIs minimizes risks and optimizes development efforts. Here, you'll learn how to explore and leverage Liferay's headless framework using various API tools.

Available API Tools

There are three general types of API tools that you can use to analyze the structure of endpoint requests and responses:

• Integrated Tools: Liferay provides an integrated API Explorer with dual API support, accessible at http[s]://[server]:[port]/o/api. This tool is ideal for quick exploration and discovery.
• Command-Line Tools: Lightweight and scriptable, command-line tools like cURL enable exploring and transferring data through terminal sessions.
• Third-Party API Tools: Liferay's headless APIs also integrate third-party API tools and UIs, offering advanced features and functionalities.

Understanding these tools empowers developers to streamline integration, automate processes, and build robust applications that leverage Liferay's headless APIs effectively.

Using Liferay's Integrated Tools

Liferay's built-in API Explorer provides an intuitive interface for exploring and interacting with both REST (Swagger) and GraphQL APIs. This tool empowers you to learn how specific APIs function within a secure environment while building custom solutions.

RESTful APIs

For REST applications, the API Explorer displays available endpoints by category. You can view request URLs, corresponding application methods, required and optional parameters, and schemas for request/response bodies. After supplying the required parameters, execute requests directly within the interface. Executed requests return the response code, headers, and body in JSON or XML format. See Consuming REST Services for more information.

GraphQL APIs

When switching to the GraphQL view, you can leverage the in-browser GraphiQL tool. This provides an interactive editor for writing, validating, and testing GraphQL APIs. The included documentation explorer provides a clear view of available fields, types, and arguments. It also includes autocomplete functionality, providing suggestions as you type to help you leverage the full potential of Liferay's GraphQL APIs. See Consuming GraphQL APIs for more information.

Business Value of API Explorer

Benefits of the integrated API Explorer include

• Integrated Interfaces: Explore REST and GraphQL endpoints without leaving the Liferay platform.
• Documentation at Hand: The inline documentation for each endpoint clarifies parameters and expected responses.
• Simplified Authentication: Bypass the need to configure OAuth flows or handle tokens for authorizing endpoints, since Liferay API Explorer uses the existing user session to call APIs.

The API Explorer is ideal for getting started with Liferay's Headless APIs, exploring endpoints, or testing basic API functionality.

Using Command-Line Tools

Command-line tools like Client URL (cURL) offer a direct and minimalistic approach to interacting with Liferay's headless APIs. These tools empower you to send HTTP requests without the need for a graphical interface. You can leverage cURL to call Liferay services with both basic authentication (not recommended for production) and OAuth 2.0, most commonly with REST API calls. See API Headers Reference for more information and example cURL commands for both REST and GraphQL.

Business Value of Command-Line Tools

Benefits of cURL and similar command-line tools include

• Customizable Requests: Add parameters, headers, and other configurations directly to your HTTP requests.
• Automated Workflows: Automate API calls through shell scripts, a powerful option for developers familiar with scripting.
• Cross-Platform Support: Already available on most operating systems, accelerate API exploration without requiring additional software installation.

Command-line tools are ideal for lightweight testing, scripting, or situations requiring advanced configurations using parameters.

Using Third-Party Tools

Liferay's headless APIs adhere to standard REST principles, making them compatible with widely-used third-party API testing services like Postman. These tools provide graphical user interfaces (GUIs) that streamline API exploration tasks such as creating and storing requests and responses, organizing API artifacts within workspaces and folders, and collaborating on tests with other users.

Business Value of Third-Party Tools

The benefits of third-party tools vary based on the chosen platform, but they generally include:

• Advanced Features: Third-party tools often provide advanced features such as collections, variables, automated tests, and visualized responses, making them robust tools for managing more complex API workflows.
• Collaboration and Versioning: Many of these tools support team collaboration, sharing API requests, and managing versions.
• Comprehensive Customization: Typically, these allow full customization of requests, including custom headers, query parameters, and body payloads.

Third-party tools are ideal for advanced testing, debugging, and managing more complex workflows, especially when collaborating with teams or working on multi-step API integrations.

Deciding Which Tooling to Use

When deciding between using API Explorer, cURL, or third-party tools to interact with Liferay's headless APIs, its important to consider these limitations:

• The API Explorer only supports parameters configurable through its UI. While this is sufficient for most use cases, there may be instances where additional parameters need to be passed via the URL, which must be done with command-line or third-party tools.
• When leveraging command-line and third-party tools, you must also handle the OAuth flow to obtain a token and include it in your API requests for all endpoints requiring authorization.

In general, start with API Explorer for learning and prototyping to quickly familiarize yourself with Liferay's APIs and confirm their behavior. Use command-line tools or third-party tools when implementing automations and dealing with more complex tasks like adding custom parameters or managing large workflows. Collaborative projects and advanced testing scenarios further benefit from leveraging third-party API tools.

Sample API Tutorials

Liferay Learn provides sample API tutorials for common use cases, such as

• Creating and managing commerce products and catalogs.
• Managing permissions for users and groups.
• Authoring and publishing content.
• Exporting and importing bulk data.

See Sample API Tutorials for a complete list of available articles and gain hands-on experience using Liferay’s headless APIs.

Conclusion

Exploring APIs and analyzing endpoints enables you to make informed decisions towards building robust, reliable applications. By understanding the strengths and limitations of each available API tool, you're empowered to select the most appropriate one for your development needs and maximize your efficiency when working with Liferay's Headless APIs.

Next, you'll learn about Liferay's multi-layered approach to securing APIs.