# REST API usage

> For the complete documentation index, see [llms.txt](https://doc.ibexa.co/en/6.0/llms.txt).

The REST API covers objects in the Cohesivo Repository with regular and custom HTTP methods, such as GET or PUBLISH, and HTTP headers.

The REST API in Cohesivo allows you to interact with the Cohesivo installation by using the HTTP protocol, following a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) 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 by using the [Public PHP API](https://doc.ibexa.co/en/6.0/api/php_api/php_api/index.md) can also be done with the REST API.

The REST API uses HTTP methods (such as `GET` and `PUBLISH`), and HTTP headers to specify the type of request.

## OpenAPI support

The REST API is built on top of [API Platform](https://api-platform.com/docs/symfony/) and meets the [OpenAPI](https://www.openapis.org/) standard.

You can download the OpenAPI specification in:

- [YAML format](https://doc.ibexa.co/en/6.0/api/rest_api/rest_api_reference/openapi.yaml)
- [JSON format](https://doc.ibexa.co/en/6.0/api/rest_api/rest_api_reference/openapi.json)

You can also generate one for your project by running one of the commands below:

```bash
php bin/console ibexa:openapi --output=openapi.json # JSON output
php bin/console ibexa:openapi --yaml --output=openapi.yaml # YAML output
```

Use the specification file with [available OpenAPI tools](https://tools.openapis.org/) to work faster with the API, for example, by generating libraries and clients for the API.

> **Note: Note**
>
> In [Symfony's `dev` environment](https://doc.ibexa.co/en/6.0/infrastructure_and_maintenance/environments/index.md), you can access a REST API reference generated for your project by visiting the `/api/ibexa/v2/doc` route in the browser.

## 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](#rest-root), every response includes further links (`href`) to related resources.

### URI prefix

[REST reference](https://doc.ibexa.co/en/6.0/api/rest_api/rest_api_reference/rest_api_reference.html), 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](https://doc.ibexa.co/en/6.0/multisite/siteaccess/siteaccess_matching/#urielement). If you need to the select a SiteAccess, see the [`X-Siteaccess` HTTP header](https://doc.ibexa.co/en/6.0/api/rest_api/rest_api_usage/rest_requests/#siteaccess).

### 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:

```http
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:

```http
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.

```bash
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](https://en.wikipedia.org/wiki/ISO_3166) codes and International Dialing Codes (IDC). You can use it 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) — use it if you need to avoid using Latin script

For details, see the [ISO-3166 glossary](https://www.iso.org/glossary-for-iso-3166.html).

## 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.
- `ValueObjectVisitor`s 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.