eZ Community » Blogs » Bertrand Dunogier » Real-life REST with eZ Publish 5

By

Bertrand Dunogier

Real-life REST with eZ Publish 5

Sunday 21 October 2012 10:26:05 am

  • Currently 5 out of 5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

As promised at the end of the engineering talk about eZ Publish 5 at the UnConference, I intend to shed some light upon our REST API.

No big fancy article yet, but a short introduction and a working example on a GIST ! Enjoy.

First, a few basic reminders. The API's specification can be found on github: https://github.com/ezsystems/ezp-next/blob/master/doc/specifications/rest/REST-API-V2.rst. It documents every possible resource in the API. You can also find the XSD files for the XML payloads in the XSD folder.

You can get an overview of it in my slides from the eZ Summer Camp in September 2012.

Due to a mix of tiredness, beta phase and time, I was only able to show how you can list, create & delete sections during our talk. I really wanted to show an article. After all, eZ Publish is a CMS, and sections aren't really content. 

After a few hours of work, and a few temporary fixes to the code, it of course works (we told you so). You can find the whole thing on GIST, as a (crappy) shell script. It uses XML as an input format, and will create an article with title, summary, body, author, image, image caption and map coordinates.

The code !

You can download the full example on GIST: https://gist.github.com/3918294. Remember that gists can be cloned, like everything else on github. As explained in the shell script, there are a few requirements:

And a last note: I suck a bit at shell scripting. Don't expect anything fancy or state in the art here :-)

Oh, and since you can clone it, you can also commit to it. Do not hesitate to push the example further and share your findings with the community !

REST operations

A few details about what is done, and how. Here, we use two REST API calls:

  1. POST /content/objects, to create a content, as a draft
  2. PUBLISH /content/objects/<contentId>/versions/<versionNumber>, to publish the created draft

In both cases, we authenticate as admin using basic authentication.

The XML payload

The most complex call is of course the first one, since we need to provide a large XML with the content's data (type, location, owner, fields and fields values). The XML is provided as a distinct file, createcontent.xml.

Among others, you will notice that the image is provided as base64. An alternative would have been to use a <value key="path"> entry, with the local path to the image.

Providing fields values

It is actually quite important to pay attention to how each field is fed with its values. The most simple ones, like TextLine, only expect a string. But author, image or map location expect more complex values. This is probably the main issue with our REST API for now: those expectations aren't really documented yet. However, valid examples are provided for every field type in the FieldType tests, in the provideInputForFromHash() data provider. Check out the one for MapLocation. You can see that it expects an array with latitude, longitude and address.

In XML format, each attribute expected by the field type is provided as a <value> node, with the attribute's name as the key attribute:

<fieldValue>
  <value key="address">26, rue de la république, Lyon</value>
</fieldValue>

When a list of values (for the Author FieldType, for instance) is expected, multiple value nodes are group within another value node:

<fieldValue>
  <value>
    <value key="name">Author 1</value>
    <value key="email">author1@example.com</value>
  </value>
  <value>
    <value key="name">Author 2</value>
    <value key="email">author2@example.com</value>
  </value>
</fieldValue>

This should be sufficient to give you a good overview, and to get started. Play with it, have fun, and let us know !

Final words

There is a LOT I would like to say and do about REST. But as we all know, we have less than a month to make eZ Publish 5.0 as good as possible. REST is among the important topics, and there are many others.

Stay in touch :-)

Proudly Developed with from