Global navigation

   Documentation Center
   eZ Studio & eZ Platform
     User Manual
     Technical Manual
     Glossary
   eZ Publish 4.x / legacy

 
eZ Publish (5.x)

eZ Publish 5.x | For eZ Platform & eZ Studio topics see Technical manual and User manual, for eZ Publish 4.x and Legacy topics see eZ Publish legacy

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

The eZ Publish 5 REST API lets you interact with an eZ Publish installation using the HTTP protocol.

Accessing the REST API

The REST API is available at the URI /api/ezp/v2/. The API from eZ Publish 4.x remains available at the same URI, /api/ezp/v1/. HTTPS is available as long as your server is properly configured.

Basics

REST (REpresentationnal State Transfer) is a web services architecture that very clowely follows the HTTP Protocol. The eZ Publish 5 REST API supports both JSON and XML in terms of request format.

Resources

The API provides a set of resources (URIs), each of them providing access to operations on a certain resource. For instance, the URI /content/objects/59 will let you interact with the content with ID 59, while /content/types/1 will let you interact with the content type 1.

HTTP verbs

It uses HTTP verbs (GET, POST, but also PUT, DELETE...), as well as HTTP headers to specify the type of request. Depending on the used HTTP verb, different actions will be possible:

  • GET /content/objects/2 will provide you with data about the content,
  • PATCH /content/objects/2 will update the content's metadata (section, main language, main location...),
  • DELETE /content/objects/2 will delete the content
  • COPY /content/objects/2 will create a copy of this content

Request headers

On top of verbs, HTTP request headers will let you personalize the request's behavior. On every resource, you can use the Accept header to indicate which format you want to communicate in, JSON or XML. This header is also used to specify the response type you want the server to send when multiple ones are available.

  • Accept: application/vnd.ez.api.Content+xml to get content (full data, fields included) as XML
  • Accept: application/vnd.ez.api.ContentInfo+json to get contentInfo (metadata only) as JSON

Authentication

At the time of the 5.0 release, two authentication methods are supported: session, and basic. Session based authentication is meant to be used for AJAX operations. It will let you re-use the visitor's session to execute operations with his/her permissions. Basic authentication will be useful when writing cross-server procedures, where one server executes operations on one/several eZ Publish instances (remote publishing, maintenance, etc).

oAuth2 will be added in the 5.1 release.

Using session based authentication

This authentication method requires a Session cookie to be sent with the request.

If this authentication method is used through a web browser, this session cookie is available as soon as your visitor
logs in. Add it as a request cookie to your REST sessions, and the user will be authenticated.

It is also possible to create a session for the visitor if he isn't logged in yet. This is done by sending a POST request
to /user/sessions, as explained in the Session based authentication chapter of the REST specifications.
chapter. Logging out is done using a DELETE request on the same resource.

Using basic authentication

Basic authentication requires the password to be sent, based 64 encoded, with the request, as explained in RFC 2617.

Most HTTP client libraries, as well as REST libraries, should support this method one way or another. This isa raw HTTP
request example:

GET / HTTP/1.1
Host: api.example.com
Accept: application/vnd.ez.api.Root+json
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

 

  • No labels