Getting started with the REST API

Installation
Nothing needs to be done here. As long as your eZ Publish 5.1 is correct= ly configured, the REST API is available on your site using the URI `/= api/ezp/v2/`. If you have installed eZ Publish in a subfolder, it pre= pends the path with this subfolder: http://example.com/sub/folder/= ezpublish/api/ezp/v2/.

Configuration

Authentication

As explained in details in the authentication chapter of this documentation, two authenticat= ion methods are currently supported: session, and basic. The API is current= ly limited to one or the other. By default, basic authentication is the act= ive mode. It requires a login / password to be sent using basic HTTP authen= tication. The alternative, session based authentication, uses a session coo= kie.

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

security.yml

=20

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

=20

Testing the API

A standard web browser is unfortunately not sufficient to really test th= e API. You can however try opening the root resource with it, using basic a= uthentication: http://admin:publish@example.co= m/api/ezp/v2/. Depending on how your browser understands XML, it w= ill either download the XML file, or open it in the browser.

To test further, you can use browser extensions, like Advanced REST clien= t for Chrome or RESTClient for Fire= fox. For command line users, HTTPie is a good tool.

Javascript exampl= e

One of the main reasons for this API is to help implementing Javascript = / AJAX interaction. You can find below an example of an AJAX call that retr= ieves ContentInfo (e.g. metadata) for a content.

REST API with Javascript

=20

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

=20

In order to test it, just save this code to some test.html file in the w= eb folder of your eZ Publish 5.1 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 you= r database. You will get the ContentInfo for object 59 in JSON.

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 brows= er. An alternative is to switch to session based authentication, as explain= ed earlier in this page. In that case, the session cookie will be transpare= ntly sent together with the request, and every AJAX call will have the same= permissions as the currently logged in user.