REST API Tutorials

The REST API v2 introduced in eZ Publish 5 allows you to interac= t 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<= /a> page to start using the API.

Basics

REST (REpresentational State T= ransfer) is a web services architecture that follows the HTTP Prot= ocol very closely. The eZ Platform REST API supports both JSON and XML<= /a> in terms of request format.

Resources

The API provides a set of URIs, each of them identifying and providing a= ccess to operations on a certain resource. For instance, the = URI /content/objects/59 will allow you to interact with the Co= ntent with ID 59, while /content/types/1 will allow you to int= eract 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 spec= ify the type of request. Depending on the used HTTP verb, different ac= tions will be possible. Example:

GET /content/objects/2 will provide y= ou 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, netw= ork firewall/security solutions and simpler web servers. To avoid issues wi= th 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 ind= icate 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 mul= tiple ones are available.

Accept: application/vnd.ez.api.Content+x= ml to get Content (full data, fields incl= uded) as XML
Accept: application/vnd.ez.api.ContentInfo+json to get ContentInfo (metadata only= ) as JSON

More information

REST specifications chapter "Media Types"<= /p>

Other headers

Other headers will be used in HTTP requests for specifying the siteacces= s to interact with, and of course authentication credentials.

Responses returned by the API will also use custom headers to indicate i= nformation about the executed operation.