Global navigation

   Documentation Center
   eZ Studio & eZ Platform
     User Manual
     Technical Manual
     Glossary
   eZ Publish 4.x / legacy

 
eZ Publish (5.x)

eZ Publish 5.x | For eZ Platform & eZ Studio topics see Technical manual and User manual, for eZ Publish 4.x and Legacy topics see eZ Publish legacy

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Added note about referencing ids in query parameters

Excerpt IncludeeZ Publish DocumentationeZ Publish DocumentationAs explained in the introduction, the REST API is based on a very limited list of general principles:

...

The API responded here with a standard 200 OK HTTP response code, which is the expected response code for a "normal" GET request. Some GET requests, like getting a content's current version, may reply with a 301 Moved permanently, or 307 Temporary redirect code.

Errors will be indicated with HTTP error codes, like 404 for Not Found, or 500 for Internal server error. The REST specifications provide the list of every HTTP response code you can expect from implemented resources.

...

It tells us we can modify the received content by patching (Accept-Patch: application/vnd.ez.api.ContentUpdate+xml;charset=utf8) it with a ContentUpdateStruct (Accept-Patch: application/vnd.ez.api.ContentUpdate+xml;charset=utf8) in XML  (Accept-Patch: application/vnd.ez.api.ContentUpdate+xml;charset=utf8) format. Of course, JSON would also work, with the proper format.

This last part means that if we send a PATCH /content/objects/23 request with a ContentUpdateStruct XML payload, we will update this Content. 

...

Depending on the resource, request & response headers will vary. For instance, creating content, or getting a content's current version will both send a Location header to provide you with the requested resource's ID.

...

This request header is the request counterpart of the Location response header. It is used in a COPY / MOVE operation, like copying a Content, on a resource to indicate where the resource should be moved to, using the ID of the destination.

...

The XML body is a serialized version of a ContentInfo struct. Most REST API calls will actually involve exchanging XML / JSON representations of the public API. This consistency, which we took very seriously, was a hard requirement for us, as it makes documentation much better by requiring less of it.

As explained above, the API has told us that we could modify content object 23 by sending a vendor/application/vnd.ez.ContentUpdate+xml. This media type again matches a Value in the API, ContentUpdateStruct.

Info

The REST API data structs mostly match a PHP Public API value object

...

Info
titleXSD files

For each XML structure known to the REST API, you can find XSD files in the XSD folder of the specifications. Those will allow you to validate your XML, and learn about every option those XML structures feature.

https://github.com/ezsystems/ezpezpublish-nextkernel/tree/master/doc/specifications/rest/xsd 

Request parameters

So far, we have seen that responses will depend on:

...

Code Block
titleGET request with limit parameter
GET /content/objects/59/versions/2/relations&limit=5 HTTP/1.1
Accept: application/vnd.ez.api.RelationList+xml
Info
titleWorking with value objects IDs

Resources that accept a reference to another resource expect this reference to be given as a REST ID, not a Public API ID. As such, the URI to request users that are assigned the role with ID 1 would be GET /api/ezp/v2/user/users?roleId=/api/ezp/v2/user/roles/1.

Custom HTTP verbs

In addition to the usual GET, POST, PUT and DELETE HTTP verbs, the API supports a few custom ones: COPY, MOVE (http://tools.ietf.org/html/rfc2518), PATCH (http://tools.ietf.org/html/rfc5789) and PUBLISH. While it should generally not be a problem, some HTTP servers may fail to recognize those. If you face this situation, you can customize a standard verb (POST, PUT) with the X-HTTP-Method-Override header.

...

Both methods are always mentioned, when applicable, in the specifications.

Specifying a siteaccess

One of the principles of REST is that the same resource (Content, Location, ContentType, ...) should be unique. The purpose is mostly to make it simple to cache your REST API using a reverse proxy like Varnish. If the same resource is available at multiple locations, cache purging becomes much more complex.

Due to this, we decided not to enable siteaccess matching with REST. In order to specify a siteaccess when talking to the REST API, a custom header, X-Siteaccess, needs to be provided. If it isn't, the default one will be used:

 

Code Block
languagenone
titleX-Siteaccess header example
GET / HTTP/1.1
Host: api.example.com
Accept: application/vnd.ez.api.Root+json
X-Siteaccess: ezdemo_site_admin