Global navigation

   Documentation Center
   eZ Studio & eZ Platform
     User Manual
     Technical Manual
   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

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

As explained in the introduction, the REST API is based on a very limited list of general principles:

  • each resource (uri) interacts with a part of the system (Content, URL aliases, user groups...),
  • for each resource, one or more verbs are available, each having a different effect (delete a Content, get a URL Alias, list user groups...),
  • media-type request headers indicate what type of data (Content / ContentInfo), and data format (JSON or XML), are expected as a response, and what can be requested.

Anatomy of a REST call

What we can learn from a GET request

This verb is used to query the API for information. It is one of the two operations web browsers implement, and the most commonly used.

The only requirement for this verb is usually the resource URI, and the accept header. On top of that, cache request headers can be added, like If-None-Match, but those aren't fully implemented yet in eZ Publish 5.0.

Load ContentInfo request

The API will reply with a few headers, as well as with the ContentInfo for content with ID 23 in XML format, as specified in the Accept header:

Load ContentInfo response

We can learn three things from those response headers:

  1. The length of our content. It doesn't really matter that much...
  2. What we are receiving, here, a ContentInfo (Content-Type: application/vnd.ez.api.ContentInfo) in XML (Content-Type: application/vnd.ez.api.ContentInfo+xml)
  3. 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
    This last part means that if we send a PATCH /content/objects/23 request with a ContentUpdateStruct XML payload, we will update this Content. 

REST will use the Accept-Patch header to indicate you how to modify the returned data.

Load ContentInfo response body  Expand source

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. The 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.

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

Value objects representation

Value objects like ContentInfo basically feature two types of fields: information fields (modified, name...) and foreign references (sectionId, mainLocationId).  



  • No labels