REST API usage¶
The REST API in Ibexa DXP allows you to interact with an Ibexa DXP installation using the HTTP protocol, following a REST interaction model.
Each resource (URI) interacts with a part of the system (content, users, search, and so on). Every interaction with the Repository than you can do from Back Office or using the Public PHP API can also be done using the REST API.
The REST API uses HTTP methods (
PUBLISH , and so on), as well as HTTP headers to specify the type of request.
The REST API is designed in such a way that the client can explore the Repository without constructing any URIs to resources.
Starting from the root resource, every response includes further links (
href) to related resources.
REST reference, for the sake of readability, uses no prefixes in the URIs.
In practice, the
/api/ibexa/v2 prefixes all REST hrefs.
URI parameters (query string) can be used on some resources. They usually serve as options or filters for the requested resource.
As an example, the request below would paginate the results and return the first 5 relations for version 3 of the Content item 59:
Working with value objects IDs¶
Resources that accept a reference to another resource expect the reference to be given as a REST URI, not a single ID. For example, the URI requesting a list of user groups assigned to the role with ID 1 is:
/ root route is answered by a reference list with the main resource routes and media-types.
It is presented in XML by default, but you can also switch to JSON output.
Alongside regular Repository interactions, there is a REST service providing a list of countries with their names, ISO-3166 codes and International Dialing Codes (IDC). It could be useful when presenting a country options list from any application.
This country list's URI is
The ISO-3166 country codes can be represented as:
- two-letter code (alpha-2) — recommended as the general purpose code
- three-letter code (alpha-3) — related to the country name
- three-digit numeric code (numeric-3) — useful if you need to avoid using Latin script
For details, see the ISO-3166 glossary.
REST communication summary¶
- A REST route (URI) leads to a REST controller action. A REST route is composed of the root prefix (
ibexa.rest.path_prefix: /api/ibexa/v2) and a resource path (for example,
- This controller action returns an
- This controller action might use the
Requestto build its result according to, for example, GET parameters, the
AcceptHTTP header, or the request payload and its
- This controller action might wrap its return in a
CachedValuewhich contains caching information for the reverse proxies.
Ibexa\Bundle\Rest\EventListener\ResponseListenerattached to the
kernel.view eventis triggered, and passes the request and the controller action's result to the
AcceptHeaderVisitorDispatchermatches one of the
Ibexa\Contracts\Rest\Output\Visitor). The role of this
Output\Visitoris to transform the value returned by the controller into XML or JSON output format. To do so, it combines an
Output\Generatorcorresponding to the output format and a
Output\Generatoris also adding the
- The matched
ValueObjectVisitorDispatcherto select the right
ValueObjectVisitoraccording to the fully qualified class name (FQCN) of the controller result. A
ValueObjectVisitoris a service tagged
ibexa.rest.output.value_object.visitorand this tag has a property
typepointing a FQCN.
ValueObjectVisitors will recursively help to transform the controller result thanks to the abstraction layer of the
Responseto send back to the client.