All posts
Liferay · 11 min read · May 11, 2026

REST vs GraphQL in Liferay: Choosing the Right API for Your Application

Liferay headless REST and GraphQL APIs side by side

The general comparison between REST and GraphQL holds everywhere: one is resource-shaped and cacheable, the other is client-shaped and flexible. Inside Liferay, though, the usual framing misleads, because the platform removes the decision the comparison is about. You do not choose an API style to implement. Both are generated from the same definition, published at the same time, enforcing the same permissions.

That single fact reshapes the whole discussion. The question is no longer which API to build, but which one a given consumer should call - and that has a different, more practical set of answers.

One definition, two surfaces

Whether the data comes from a built-in headless application, an object definition, or an application you generated yourself, the platform derives both surfaces from one description of the resource. A field added to an object appears in the REST payload and the GraphQL schema together. A new endpoint in a generated application gets a GraphQL query without anyone writing a resolver.

  • Built-in headless applications expose content, users, accounts and more under their own REST paths.
  • Object definitions publish their own endpoints as soon as the object is published.
  • Generated applications produce both surfaces from the same OpenAPI-style specification.
  • All of them appear in the single GraphQL endpoint alongside everything else.

The practical consequence is that the specification is the real artefact. Time spent getting resource granularity, field names, and relationships right pays off twice, because both API styles inherit the same shape. Time spent arguing about which style to adopt pays off not at all.

What REST gives you that GraphQL does not

Liferay's REST surface is more capable than the usual comparison assumes, because the query features people normally reach for GraphQL to get are already present as parameters.

http
GET /o/c/applications
    ?filter=status eq 'SUBMITTED' and amount gt 100000
    &sort=submittedDate:desc
    &page=1&pageSize=20
    &fields=id,applicantName,amount,status
    &nestedFields=documents
Filtering, sorting, paging, field selection and related records - without a query language.

On top of that, REST keeps a set of advantages that are structural rather than stylistic:

  • HTTP caching, proxies and CDNs work normally, because responses are addressable by URL.
  • File upload is straightforward multipart; GraphQL has no good answer here.
  • Batch import and export endpoints exist for bulk operations and have no GraphQL equivalent.
  • Every endpoint is browsable and testable through the published API explorer.
  • Rate limiting, logging and gateway policies apply per path, which operations teams rely on.

What GraphQL gives you that REST does not

GraphQL earns its place in exactly one situation, and it is a common one: a screen that assembles data from several unrelated resources. A dashboard showing the current user, their organisation's open applications, the reference picklists, and a notification count is four REST calls and one GraphQL query.

graphql
query DashboardBootstrap {
  myUserAccount { id name emailAddress }
  applications(filter: "status eq 'SUBMITTED'", pageSize: 5) {
    items { id applicantName amount status }
    totalCount
  }
}
The composition case: several resources, one round trip, one loading state.

The saving is not only network time. A single request means a single loading state and a single error path in the front end, which removes a surprising amount of code from any screen that would otherwise coordinate four independent fetches.

Where the differences are smaller than expected

Two assumptions travel with the general comparison and do not survive contact with Liferay.

The first is that GraphQL gives clients arbitrary query power. It does not here - filtering, sorting and paging are still arguments shaped like the REST parameters, because both are generated from the same resource definition. GraphQL lets you compose several resources in one request; it does not let you invent queries the resource does not support.

The second is that the API choice has security implications. It does not. Permissions are enforced in the service layer beneath both surfaces, so a user who cannot read a record gets nothing back either way. Choosing GraphQL neither weakens nor strengthens authorisation, and no API-level filtering substitutes for correct permissions.

Choosing per consumer

ConsumerBetter fitWhy
Composite dashboard or bootstrap screenGraphQLSeveral resources, one round trip, one loading state
List, detail and edit screensRESTSingle resource, cacheable, simplest to debug
Creates, updates and deletesRESTClear semantics, consistent error handling
File upload and downloadRESTMultipart and binary responses
Bulk load or exportREST batch endpointsDesigned for volume; no GraphQL equivalent
Mobile client on a slow networkGraphQLPayload size and round trips matter most
Third-party or partner integrationRESTLower barrier, standard tooling, easier to document
The unit of decision is the consumer and the screen, not the project.

The pitfalls worth knowing in advance

  • Deep nesting in GraphQL can turn one query into many underlying fetches; keep composition wide rather than deep.
  • Page size limits apply to both surfaces, so a nested collection may be silently truncated - always read the returned count.
  • GraphQL responses return HTTP 200 with an errors block, so client error handling must inspect the body rather than the status code.
  • Caching a GraphQL POST is not something a CDN will do for you; high-traffic public reads belong on REST.
  • Mixing both styles inside one screen doubles the auth and error handling code for no benefit - choose one per screen.

A default worth adopting

For most projects a simple default works: REST for writes, uploads, integrations and ordinary single-resource screens; GraphQL for the two or three composite read-heavy screens that genuinely need it. Above all, resist writing a third, hand-rolled endpoint style because neither felt perfect - that custom endpoint will not inherit the filtering, permissions, documentation or GraphQL schema the platform generates, and it becomes the part of the backend nobody wants to maintain.

Conclusion

Liferay turns REST against GraphQL from an architectural commitment into a per-call choice, and that is a better problem to have. Invest in the resource definitions, because both surfaces inherit their quality. Then let each screen call whichever surface makes it simplest - REST for the predictable majority, GraphQL for composition - and stop treating the choice as something that needs to be made once for the whole project.

Contact

Let’s connect

Have a Liferay or Backend project you’d like to talk through? Fill in the form and I’ll get back to you.

Book Calendar