# REST API usage

> For the complete documentation index, see [llms.txt](https://doc.ibexa.co/en/saas/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 that you can do from the back office 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 meets the [OpenAPI](https://www.openapis.org/) standard.

You can download the OpenAPI specification in:

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

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.

## 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/saas/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. If you need to the select a SiteAccess, see the [`X-Siteaccess` HTTP header](https://doc.ibexa.co/en/saas/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).