Skip to content
  • Documentation >
  • API >
  • REST API >
  • REST API usage >
  • REST API usage

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 (like content, users or search). 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 (such as GET and PUBLISH), as well as HTTP headers to specify the type of request.

URIs

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.

URI prefix

REST reference, for the sake of readability, uses no prefixes in the URIs. In practice, the /api/ibexa/v2 prefixes all REST hrefs.

This prefix immediately follows the domain, and you can't use the URIElement SiteAccess matcher. If you need to the select a SiteAccess, see the X-Siteaccess HTTP header.

URI parameters

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:

1
2
GET /content/objects/59/versions/3/relations?limit=5 HTTP/1.1
Accept: application/vnd.ibexa.api.RelationList+xml

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:

1
GET /api/ibexa/v2/user/groups?roleId=/api/ibexa/v2/user/roles/1 HTTP/1.1

REST root

The / root route is answered by a reference list with the main resource routes and media-types. It's presented in XML by default, but you can also switch to JSON output.

1
2
curl https://api.example.com/api/ibexa/v2/
curl -H "Accept: application/json" https://api.example.com/api/ibexa/v2/

Country list

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 /services/countries.

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, /content/objects/{contentId}).
  • This controller action returns an Ibexa\Rest\Value descendant.
    • This controller action might use the Request to build its result according to, for example, GET parameters, the Accept HTTP header, or the request payload and its Content-Type HTTP header.
    • This controller action might wrap its return in a CachedValue which contains caching information for the reverse proxies.
  • The Ibexa\Bundle\Rest\EventListener\ResponseListener attached to the kernel.view event is triggered, and passes the request and the controller action's result to the AcceptHeaderVisitorDispatcher.
  • The AcceptHeaderVisitorDispatcher matches one of the regexps of an ibexa.rest.output.visitor service (an Ibexa\Contracts\Rest\Output\Visitor). The role of this Output\Visitor is to transform the value returned by the controller into XML or JSON output format. To do so, it combines an Output\Generator corresponding to the output format and a ValueObjectVisitorDispatcher. This Output\Generator is also adding the media-type attributes.
  • The matched Output\Visitor uses its ValueObjectVisitorDispatcher to select the right ValueObjectVisitor according to the fully qualified class name (FQCN) of the controller result. A ValueObjectVisitor is a service tagged ibexa.rest.output.value_object.visitor and this tag has a property type pointing a FQCN.
  • ValueObjectVisitors recursively help to transform the controller result thanks to the abstraction layer of the Generator.
  • The Output\Visitor returns the Response to send back to the client.