Getting started with the REST API

Installation
No special preparations are necessary to use the REST API. As long as yo= ur eZ Platform is correctly configured, the REST API is available on your s= ite using the URI `/api/ezp/v2/`. If you have installed eZ Platf= orm in a subfolder, prepend the path with this subfolder: http://example.com/sub/folder/e= zpublish/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 = currently supported: session and basic. By default, session authentication = is the active mode, it uses a session cookie. The alternative, basic auth a= uthentication requires a login / password to be sent using basic HTTP authentication.

To enable basic auth based authentication, you need to edit = app/config/security.yml and uncomme= nt the configuration block about REST

security.yml

=20

security:
    # ...
    firewalls:
        # ...
        ezpublish_rest:
            pattern: ^/api/ezp/v2
            ezpublish_http_basic:
                realm: eZ Platform 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 the session authenti= cation: http://example.com/api/ezp/v2/.<= /span> Depending on how your browser understands XML, it will either d= ownload 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 implement JavaScript / A= JAX interaction. You can see here an example of an AJAX call that retrieves= 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'),
    request =3D new XMLHttpRequest();

log.innerHTML =3D "Loading the content info from " + resource + "...";

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 Platform installation. If you use the rewrite rules, d= on't forget to allow this file to be served directly.

If necessary, substitute 59 with the Content item ID of an = item from your database. You will get the ContentInfo for item 59 in JSON e= ncoding.

Note that by default, session authentication is used. This means that th= e session cookie will be transparently sent together with the request, and = every AJAX call will have the same permissions as the currently logged in u= ser.

JavaScript REST Client

To ease the use of the eZ Platform REST API, we provide a JavaScript RES= T Client. Its basic usage is explained in Using the JavaScript REST API Client.<= /p>