Introduction

One of the biggest strengths of Liferay DXP is its Headless API ecosystem. Whether we're working with Custom Objects, Web Content, Documents, Commerce, or custom REST Builder APIs, Liferay provides well-designed REST endpoints that are easy to integrate with modern frontend applications.

For simple data retrieval, the existing APIs work extremely well.

For example:

GET /o/c/employees

Filtering is also straightforward:

GET /o/c/employees?filter=department eq 'IT'

However, as applications become more sophisticated, search requirements become significantly more complex. Dynamic filters, nested conditions, relationship queries, multiple sorting options, pagination, field selection, and AI-generated search requests can quickly turn a clean URL into something difficult to read and maintain.

Recently I came across RFC 10008, which introduces a new HTTP method named QUERY.

Although the RFC is still new and not yet widely supported by frameworks such as Spring Boot or Jakarta REST, it immediately made me think about Liferay Headless APIs and how this method could improve the developer experience in the future.

This article is not a proposal to replace existing APIs, but rather an exploration of how HTTP QUERY could fit naturally into Liferay's Headless ecosystem.

The Current Experience
Suppose we have a Liferay Object called Employee.

Today we retrieve records like this:

• GET /o/c/employees

If we want filtering:

• GET /o/c/employees?filter=(department eq 'IT' and salary gt 50000)

Sorting:

• GET /o/c/employees?sort=name:asc

Pagination:

• GET /o/c/employees?page=1&pageSize=20

Selecting fields:

• GET /o/c/employees?fields=id,name,email

Liferay already provides excellent support for these features.

The challenge appears when all of these capabilities need to be combined into a single request.

A real-world URL may eventually contain:

• complex filter expressions
• nested logical operators
• relationship filters
• multiple sorting fields
• pagination
• selected fields
• nested fields

The URL becomes increasingly difficult to understand.

Why GET Starts Showing Its Limits
GET requests were designed around URL parameters.

They work perfectly for small amounts of information.

But enterprise applications often require much richer search criteria.

Consider a dynamic search screen where users can create rules such as:

• Department = IT
• Salary > 50,000
• Experience >= 5 years
• Location = India
• Status = Active

The frontend eventually has to generate a filter string similar to:

(department eq 'IT' and salary gt 50000 and experience ge 5 and location eq 'India' and status eq 'Active')
Now imagine adding multiple OR groups, relationships, date ranges, and custom object fields.

The filter quickly becomes difficult to read, difficult to debug, and difficult to generate programmatically.

The Common Workaround
Many REST APIs solve this problem by creating a search endpoint using POST.

For example:

POST /employees/search
{
  "department": "IT",
  "salary": {
    "gt": 50000
  },
  "experience": {
    "gte": 5
  }
}
Technically this works very well.

1. However, semantically, POST usually represents an operation that creates or processes resources.
2. Searching does neither.
3. We're simply retrieving data.

This is exactly the problem that RFC 10008 attempts to solve.

What is HTTP QUERY?
RFC 10008 introduces a new HTTP method called QUERY.

Unlike GET, QUERY allows a request body while still representing a safe, read-only operation.

For example:

QUERY /o/c/employees
Content-Type: application/json
{
  "department": "IT",
  "salary": {
    "gt": 50000
  }
}

 

• Nothing is created.
• Nothing is updated.
• Nothing is deleted.
• The request simply asks the server to return matching data.

Conceptually, this feels like a very natural fit for search operations.

How Could This Help Liferay?

 

Structured Search Requests

Instead of encoding complex logic inside URLs:

GET /o/c/employees?filter=(department eq 'IT' and salary gt 50000)
Developers could send structured JSON.

{
  "filter": {
    "department": "IT",
    "salary": {
      "gt": 50000
    }
  },
  "sort": [
    {
      "field": "name",
      "direction": "ASC"
    }
  ],
  "page": 1,
  "pageSize": 20
}
JSON is easier to generate, validate, and debug than long query strings.

2. Better Support for Dynamic Liferay Objects

One of Liferay's greatest strengths is that administrators can create Objects without writing code.

Every environment may have different:

• object definitions
• custom fields
• relationships
• picklists
• validations

As these object models become increasingly dynamic, representing search criteria as structured JSON becomes much more natural than constructing long filter expressions.

3. Simpler Relationship Queries

Today relationship filtering often relies on filter expressions.

Imagine instead writing:

{
  "department": {
    "name": "Engineering"
  }
}

This structure is easier for developers to understand and aligns more closely with how object relationships are represented.

4. Better Low-Code Experience

• Liferay promotes low-code application development.
• Visual filter builders usually generate JSON internally.

Today the flow often looks like this:
UI
 ↓
JSON
 ↓
Convert to filter string
 ↓
GET request
--------------------------------------------------------------------
With QUERY the process could become:
UI
 ↓
JSON
 ↓
QUERY request

The conversion layer disappears.

5. Better AI Integration

• As AI becomes part of enterprise applications, structured APIs become increasingly valuable.
• Large Language Models naturally generate JSON.

Generating:

{
  "department": "IT",
  "salary": {
    "gt": 50000
  }
}

 

• is generally simpler than generating complex filter syntax.
• For future AI-powered Liferay applications, structured query bodies could provide a cleaner integration model.

6. Easier Validation

• A structured request body can be validated using existing JSON validation techniques.
• Instead of parsing long filter strings, APIs could validate request objects before executing searches.
• This may simplify both server-side validation and client-side development.

If HTTP QUERY eventually gains widespread adoption across browsers, frameworks, API gateways, and OpenAPI tooling, it could become an interesting addition to Liferay's Headless platform.

Developers could continue using GET for simple retrieval while choosing QUERY whenever complex, structured search criteria are required.

Final Thoughts

• RFC 10008 is still relatively new, and widespread adoption will likely take time.
• However, reading the specification made me think about the future of Liferay Headless APIs.
• As Liferay continues investing in Headless delivery, Custom Objects, low-code development, and AI-powered applications, the ability to express rich, structured, read-only searches through HTTP QUERY feels like a natural evolution.

Perhaps this isn't something Liferay should implement today.

But it is certainly an interesting conversation for the community.

I'd love to hear what other Liferay developers think.

1. Would HTTP QUERY make your Headless APIs easier to consume?
2. Would you use it for Custom Objects?
3. Do you see value in structured search requests over long filter expressions?

Let's discuss.