The REST API #

This page is for developers who read or write content from another application: a mobile app, a JavaScript front end, an integration. The DXP ships the REST API v2 (ibexa/rest), "a headless CRUD REST API" in the skeleton's words.

Contents #

1. Where it lives
2. What it covers
3. Authentication
4. Trying it
5. CORS
6. Before you build a client

Where it lives #

The routes are imported under the prefix parameter ibexa.rest.path_prefix (see config/routes/ibexa_rest.yaml). In the installed v5 package its default is /api/ibexa/v2. The skeleton's guide and README show /api/ezp/v2/, the prefix of the older lines. Check what your project really serves:

php bin/console debug:container --parameter=ibexa.rest.path_prefix
php bin/console debug:router | grep -m5 "ibexa.rest"

Use the value your project prints in every client, and keep it in one configuration value of the client.

What it covers #

The REST API exposes the content repository: content items and their versions, content types, locations and the tree, sections, object states, languages, users, user groups, roles, URL aliases, trash, bookmarks and search (views). Each resource has its own media type, and clients ask for JSON or XML with the Accept header.

Authentication #

Anonymous requests see what the Anonymous role may read.

Trying it #

BASE="https://127.0.0.1:8000/api/ibexa/v2"       # use your prefix
curl -s -H "Accept: application/vnd.ibexa.api.Root+json" "$BASE/"
curl -s -H "Accept: application/vnd.ibexa.api.Location+json" "$BASE/content/locations/1/2"

The root resource lists the entry points of the API. If a media type name differs in your version, the root response shows the names it uses.

CORS #

Browsers on another origin need CORS. The skeleton's guide sets CORS_ALLOW_ORIGIN in .env.local; widen it only to the origins of your own clients (Environment variables).

Before you build a client #

• Decide what a client may write; give its user a role with only those policies.
• Plan caching: anonymous GET responses pass through the HTTP cache (HTTP cache).
• Keep the API prefix and media types out of hard-coded strings scattered over the client.
• For read-heavy front ends, compare with GraphQL (GraphQL and GraphiQL).

Related pages #

• JWT authentication
• Headless with the DXP
• Headless with the REST API (for organizations)
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.