REST API Guide
The REST API v2 introduced in eZ Platform allows you to interact with an eZ Platform installation using the HTTP protocol, following a REST interaction model.
Accessing the REST API
The REST API is available at the URI /api/ezp/v2 . HTTPS is available as long as your server is properly configured. Refer to the Getting started with the REST API page to start using the API.
Basics
REST (REpresentational State Transfer) is a web services architecture that follows the HTTP Protocol very closely. The eZ Platform REST API supports both JSON and XML in terms of request format.
Resources
The API provides a set of URIs, each of them identifying and providing access to operations on a certain resource. For instance, the URI /content/objects/59 will allow you to interact with the Content with ID 59, while /content/types/1 will allow you to interact with the Content Type with ID 1.
HTTP verbs
It uses HTTP verbs ( GET , POST , but also PUT , DELETE , etc...), as well as HTTP headers to specify the type of request. Depending on the used HTTP verb, different actions will be possible. Example:
- GET /content/objects/2 will provide you with data about Content #2,
- PATCH /content/objects/2 will update the Content #2's metadata (section, main language, main location...),
- DELETE /content/objects/2 will delete Content #2,
- COPY /content/objects/2 will create a copy of this Content.
Caution with custom HTTP verbs
Using custom HTTP verbs, those besides the standard (GET, POST, PUT, DELETE, OPTIONS, TRACE), can cause issues with several HTTP proxies, network firewall/security solutions and simpler web servers. To avoid issues with this REST API allows you to set these using a HTTP header instead using HTTP verb POST. Example: X-HTTP-Method-Override: PUBLISH
Media type headers
On top of verbs, HTTP request headers will allow you to personalize the request's behavior. On every resource, you can use the Accept header to indicate which format you want to communicate in, JSON or XML. This header is also used to specify the response type you want the server to send when multiple ones are available.
- Accept: application/vnd.ez.api.Content+xml to get Content (full data, fields included) as XML
- Accept: application/vnd.ez.api.ContentInfo+json to get ContentInfo (metadata only) as JSON
More information
Other headers
Other headers will be used in HTTP requests for specifying the siteaccess to interact with, and of course authentication credentials.
Responses returned by the API will also use custom headers to indicate information about the executed operation.
In this topic:
Related topics:
In this section
- Getting started with the REST API No special preparations are necessary to use the REST API. As long as your eZ Platform is correctly configured, the REST API is available on your site using the URI /api/ezp/v2/. If you have installed eZ Platform in a subfolder, prepend the path with this subfolder: http://example.com/sub/folder/exp
- General REST usage As explained in the introduction, the REST API is based on a very limited list of general principles:
- REST API Authentication The REST API supports two authentication methods: session, and basic.
- Error handling Error handling in the REST API is fully based on HTTP error codes. As a web developer, you are probably familiar with the most common ones: 401 Unauthorized, 404 Not Found or 500 Internal Server Error. The REST API uses those, along with a few more, to allow proper error handling.
- Extending the REST API The eZ Platform REST API comes with a framework that makes it quite easy to extend the API for your own needs.
- REST API Countries list Countries list is a REST service that gives access to an ISO-3166 formatted list of world countries. It is useful when presenting a country options list from any application.
- Using the JavaScript REST API Client The JavaScript REST API Client is a JavaScript library meant to ease the use of the eZ Platform REST API. For now, it can only be used in a web browser.
- REST API reference The complete reference (specification) of the REST API resources is found bundled with your software, or online:
Contributors
- Dominika Kurek
- David Christian Liedle Updated
Comments
Add a comment