# REST Responses ## Response code The following list of available HTTP response status codes gives an overview of the meaning of each code. For code details per resource, see the [REST API reference](https://doc.ibexa.co/en/latest/api/rest_api/rest_api_reference/rest_api_reference.html). | Code | Message | Description | | ----- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | OK | The resource has been found. | | `201` | Created | The request to create a new item has succeeded. The response `Location` header indicates where you can find the created item. | | `204` | No Content | The request has succeeded and there is no additional information in the response header or body (for example when publishing or deleting). | | `301` | Moved Permanently | The resource shouldn't be accessed this way. The response `Location` header indicates the proper way. | | `307` | Temporary Redirect | The resource is available at another URL considered as its main. The response `Location` header indicates this main URL. | | `400` | Bad Request | The input (payload) doesn't have the proper schema for the resource. | | `401` | Unauthorized | The user doesn't have the permission to make this request. | | `403` | Forbidden | The user has the permission but action can't be performed because of Repository logic (for example, when trying to create an item with an already existing ID or identifier, when attempting to update a version in another state than draft). | | `404` | Not Found | The requested object (or a request data like the parent of a new item) hasn't been found. | | `405` | Method Not Allowed | The requested resource doesn't support the HTTP verb that was used. | | `406` | Not Acceptable | The request's `Accept` header isn't supported. | | `409` | Conflict | The request is in conflict with another part of the repository (for example, trying to create a new item with an identifier already used). | | `415` | Unsupported Media Type | The request payload media type doesn't match the media type specified in the request header. | | `500` | Internal Server Error | The server encountered an unexpected condition, usually an exception, which prevents it from fulfilling the request, like database down, permissions or configuration error. | | `501` | Not Implemented | Returned when the requested method hasn't yet been implemented. For Ibexa DXP, most of users, user groups, content items, locations and content types have been implemented. Some of their methods, and other features, may return a 501. | ## Response headers A resource's response may contain metadata in its HTTP headers. Note For information about the `Allow` response header, see the [`OPTIONS` method](https://doc.ibexa.co/en/latest/api/rest_api/rest_api_usage/rest_requests/#options-method). ### Content-Type header When a response contains an actual HTTP body, the `Content-Type` header specifies what the body contains. The `Content-Type` header's value is a [media type](https://doc.ibexa.co/en/latest/api/rest_api/rest_api_usage/rest_requests/#media-types), like with the request `Accept` and `Content-Type` headers. For example, the first following request without an `Accept` header returns a default format indicated in the response `Content-Type` header, while the second request shows that the response is in the requested format. ``` GET /content/objects/52 HTTP/1.1 ``` ``` HTTP/1.1 200 OK Content-Type: application/vnd.ibexa.api.ContentInfo+xml ``` ``` GET /content/objects/52 HTTP/1.1 Accept: application/vnd.ibexa.api.Content+json ``` ``` HTTP/1.1 200 OK Content-Type: application/vnd.ibexa.api.Content+json ``` ### Accept-Patch header When available, the `Accept-Patch` tells how the received item could be modified with `PATCH`. The following examples also shows that the format (XML or JSON) is adapted: ``` GET /content/objects/52 HTTP/1.1 ``` ``` HTTP/1.1 200 OK Content-Type: application/vnd.ibexa.api.ContentInfo+xml Accept-Patch: application/vnd.ibexa.api.ContentUpdate+xml ``` ``` GET /content/objects/52 HTTP/1.1 Accept: application/vnd.ibexa.api.Content+json ``` ``` HTTP/1.1 200 OK Content-Type: application/vnd.ibexa.api.Content+json Accept-Patch: application/vnd.ibexa.api.ContentUpdate+json ``` Those example `Accept-Path` headers above indicate that the content could be modified by sending a [ContentUpdateStruct](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-Content-ContentUpdateStruct.html) in XML or JSON. ### Location header For example, [creating content](https://doc.ibexa.co/en/latest/api/rest_api/rest_api_reference/rest_api_reference.html#managing-content-create-content-type) and [getting a content item's current version](https://doc.ibexa.co/en/latest/api/rest_api/rest_api_reference/rest_api_reference.html#tag/Objects/operation/api_contentobjects_contentIdcurrentversion_get) both send a `Location` header to provide you with the requested resource's ID. Those particular headers generally match a specific list of HTTP response codes. `Location` is mainly sent alongside `201 Created`, `301 Moved permanently`, `307 Temporary redirect responses`. In the following example, the content item's remote ID 34720ff636e1d4ce512f762dc638e4ac corresponds to the ID 52: ``` GET /content/objects?remoteId=34720ff636e1d4ce512f762dc638e4ac" HTTP/1.1 ``` ``` HTTP/1.1 307 Temporary Redirect Location: /content/objects/52 ``` In the following example, an erroneous slash has been added to demonstrate the 301 case: ``` GET /content/objects?remoteId=34720ff636e1d4ce512f762dc638e4ac" HTTP/1.1 ``` ``` HTTP/1.1 301 Moved Permanently Location: /content/objects?remoteId=34720ff636e1d4ce512f762dc638e4ac ``` cURL can follow those redirections. On CLI, there is the `--location` option (or its shorthand `-L`). In PHP, you can achieve the same effect with `CURLOPT_FOLLOWLOCATION`. The following command-line example follows the two redirections above and the `Accept` header is propagated: ``` curl --head --location --header "Accept: application/vnd.ibexa.api.Content+json" "https://api.example.com/api/ibexa/v2/content/objects/?remoteId=34720ff636e1d4ce512f762dc638e4ac" ``` ``` HTTP/1.1 200 OK Content-Type: application/vnd.ibexa.api.Content+json ``` ### Cross-origin [Cross-Origin Resource Sharing (CORS)](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) can allow the REST API to be reached from a page on another domain. For more information about CORS, see [WHATWG's CORS Protocol specification](https://fetch.spec.whatwg.org/#cors-protocol) and [Overview of CORS on developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). CORS support is provided by the third party [nelmio/cors-bundle](https://packagist.org/packages/nelmio/cors-bundle). You can read more about it in [NelmioCorsBundle's README](https://github.com/nelmio/NelmioCorsBundle/blob/master/README.md). Using CORS isn't limited to REST API resources and can be used for any resource of the platform. The CORS bundle adds an `Access-Control-Allow-Origin` header to the response. #### Configuration To enable CORS, add regular expression for an allowed domain using the `.env` variable `CORS_ALLOW_ORIGIN`. For example, to allow the [JS test](https://doc.ibexa.co/en/latest/api/rest_api/rest_api_usage/testing_rest_api/#js) to be executed alongside this page, you could add the following to an `.env` file (like the `.env.local`): `CORS_ALLOW_ORIGIN=^https?://doc.ibexa.co`. To add several domains, filter on URIs, or change the default (like not allowing all the methods), refer to [NelmioCorsBundle Configuration Documentation](https://symfony.com/bundles/NelmioCorsBundle/current/index.html#configuration) to learn how to edit `config/packages/nelmio_cors.yaml`. ## Response body The Response body is often a serialization in XML or JSON of an object as it could be retrieved using the Public PHP API. For example, the resource `/content/objects/52` with the `Accept: application/vnd.ibexa.api.ContentInfo+xml` header returns a serialized version of a [ContentInfo](https://doc.ibexa.co/en/latest/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-Content-ContentInfo.html) object. ``` curl https://api.example.com/content/objects/52 --header 'Accept: application/vnd.ibexa.api.ContentInfo+xml'; ``` ``` Ibexa Digital Experience Platform Ibexa Digital Experience Platform
2015-09-17T09:22:23+00:00 2015-09-17T09:22:23+00:00 eng-GB 1 true false PUBLISHED ``` The response body XML can contain two types of nodes: - Final nodes that fully give an information as a scalar value - Reference nodes which link to `href` where a new resource of a given `media-type` can be explored if you need to know more