DxpLife The practical Liferay DXP knowledge hub
Talk to us

Home/Field Guide/Client extensions & APIs

CONCEPT 11

Headless REST, GraphQL, and API Explorer

Read the real OpenAPI contract, query supported fields, and build for upgrades.

10 minAPI contract is build-specific

Start with a contract from your server

Open /o/api and select an installed REST application. The spec tells you its base path, methods, schemas, query options, and response types. Standard applications commonly live under a family such as /o/headless-delivery/v1.0. A custom Object commonly gets a path under /o/c/. When the Object is site scoped, use the generated scope-aware list or create endpoint.

REST is a convenient default for explicit operations, list queries, and integration testing. GraphQL lets a caller select response fields and related data where supported. Its schema and limits are also version-specific. Cap nested work, test resolver permissions, and review actual errors from the GraphQL response body.

Query an Object collection

bash
curl --fail-with-body --get "$BASE/o/c/partnerrequests" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "page=1" \
  --data-urlencode "pageSize=20"

This is an illustrative company-scoped path. Use the exact plural API path from API Explorer. Inspect items and the paging metadata before advancing. filter, sort, search, field selection, and relationship expansion depend on the operation and field configuration. Start with one known record before composing a complex filter.

Write with intention

Use POST to create, PATCH for a partial update where offered, and read the specific semantics before using PUT. Confirm an ERC-addressed operation exists before using it. If an HTTP timeout occurs after submission, reconcile the current record before retrying a potentially duplicating write. Pin representative requests and expected error responses as contract tests.

Where API Builder fits

API Builder can compose APIs from Objects where the feature is available. The product documentation labels it beta for the documented release line. Check the feature flag and status on your target before relying on it in production. REST Builder is the Java option when you need a custom contract and hosting supports an in-process module.

Official references