Installation

Nothing needs to be done for this to work. As long as your eZ Publish 5 is correctly configured, the REST API is available on your site using the URI /api/ezp/v2/. If you have installed eZ Publish in a subfolder, prepend the path with this subfolder: http://example.com/sub/folder/ezpublish/api/ezp/v2/.

Configuration

Authentication

As explained in more detail in the authentication chapter, two authentication methods are currently supported: session, and basic. By default, basic authentication is the active mode. It requires a login / password to be sent using basic HTTP authentication. The alternative, session based authentication, uses a session cookie. 

To enable session based authentication, you need to edit ezpublish/config/security.yml, and comment out / remove the configuration block about REST

security:
    # ...
    firewalls:
        # ...
        ezpublish_rest:
            pattern: ^/api/ezp/v2
            ezpublish_http_basic:
                realm: eZ Publish REST API

Testing the API

A standard web browser is not sufficient to fully test the API. You can however try opening the root resource with it, using basic authentication: http://admin:publish@example.com/api/ezp/v2/. Depending on how your browser understands XML, it will either download the XML file, or open it in the browser.

To test further, you can use browser extensions, like Advanced REST client for Chrome or RESTClient for Firefox, or dedicated tools. For command line users, HTTPie is a good tool.

Javascript example

One of the main reasons for this API is to help implementing Javascript / AJAX interaction. You can see here an example of an AJAX call that retrieves ContentInfo (e.g. metadata) for a content item.

<pre id="rest-output"></pre>
<script>
var resource = '/api/ezp/v2/content/objects/59',
    log = document.getElementById( 'rest-output' );
log.innerHTML = "Loading the content info from " + resource + "...";
   
var request = new XMLHttpRequest();
request.open('GET', resource, true);
request.onreadystatechange = function () {
    if ( request.readyState === 4 ) {
        log.innerHTML = "HTTP response from " + resource + "\n\n" + request.getAllResponseHeaders() + "\n" + request.responseText;
    }
};
request.setRequestHeader('Accept', 'application/vnd.ez.api.ContentInfo+json');
request.send();
</script>

In order to test it, just save this code to some test.html file in the web folder of your eZ Publish 5 installation. If you use the rewrite rules, don't forget to allow this file to be served directly.

If necessary, change 59 with the content object id of an object from your database. You will get the ContentInfo for object 59 in JSON encoding.  

Note that by default, basic authentication is used. You can either add a valid login/password in the URI, or submit them when asked to by the browser. An alternative is to switch to session based authentication, as explained earlier in this page. In that case, the session cookie will be transparently sent together with the request, and every AJAX call will have the same permissions as the currently logged in user.