Getting started with the REST API

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 U= RI `/api/ezp/v2/`. If you have installed eZ Publish in a subfold= er, prepend the path with this subfolder: http:= //example.com/sub/folder/ezpublish= /api/ezp/v2/.

Please note that the `/api/ezp/v2` prefix will be used in all= REST hrefs, but not in URIs.

Configuration

Authentication

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

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 not sufficient to fully test the API. You can = however try opening the root resource with it, using basic authentication:&= nbsp;http://admin:publish@example.com/api/ezp/v2/= . Depending on how your browser understands XML, it will ei= ther 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, or dedicated tools. 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 see here an example of an AJAX call that retrie= ves ContentInfo (e.g. metadata) for a content item.

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 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 encoding. &n= bsp;

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.