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.
As explained in more detail in the authentication page, two authentication methods are c= urrently supported: session and basic. By default, session authentication i= s the active mode, it uses a session cookie. The alternative, basic auth au= thentication requires a login / password to be sent using basic HTTP authen= tication.
To enable basic auth based authentication, you need to edit =
app/config/security.yml and uncomme=
nt the configuration block about REST
security:
# ...
firewalls:
# ...
ezpublish_rest:
pattern: ^/api/ezp/v2
ezpublish_http_basic:
realm: eZ Platform REST API=20
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.
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:
<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= .