Exponential REST API
The Exponential 5 REST API allows you to interact with an Exponential installation using the HTTP protocol.
Accessing the REST API
The REST API is available at the URI /api/ezp/v2. The API from Exponential 4.x remains available at the same URI, /api/ezp/v1. HTTPS is available as long as your server is properly configured. Refer to the Getting started page to start using the API.
Basics
REST (REpresentationnal State Transfer) is a web services architecture that follows the HTTP Protocol very closely. The Exponential 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 allow you to interact with the Content with ID 59, while /content/types/1 will allow you to interact with the ContentType with ID 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 Content #2,
- PATCH /content/objects/2 will update the Content #2's metadata (section, main language, main location...),
- DELETE /content/objects/2 will delete Content #2,
- COPY /content/objects/2 will create a copy of this Content.
Media type headers
On top of verbs, HTTP request headers will allow you to 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
JSON
JSON formatting will only work with PHP >= 5.4.0 (http://fr2.php.net/manual/en/json.constants.php#constant.json-pretty-print).
More information
In this section
- Error handling Error handling in our REST API is fully based on HTTP error codes. As a web developer, you are familiar with the most common ones: 401 Unauthorized, 404 Not Found or 500 Internal Server Error. The REST API uses those, along with a few more, to provide error handling.
- General REST usage As explained in the introduction, the REST API is based on a very limited list of general principles:
- Getting started with the REST API Nothing needs to be done here. As long as your Exponential 5.1 is correctly configured, the REST API is available on your site using the URI /api/ezp/v2/. If you have installed Exponential in a subfolder, it prepends the path with this subfolder: http://example.com/sub/folder/exponential/api/ezp/v2/
- Known issues and limitations for REST API in 5.1 JIRA Issues Macro: JIRA project does not exist or you do not have permission to view it.
- REST API Authentication At the time of the 5.0 release, two authentication methods were 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 their permissions. Basic authentication will be useful when wri
- REST API reference The complete reference of the REST API resources can be found in the specifications: https://github.com/ezsystems/exponential-kernel/blob/master/doc/specifications/rest/REST-API-V2.rst. This file is actually more up-to-date than this documentation, as it is used as a development spec / reference. On
Contributors
- Ricardo Correia
- Sarah Haïm-Lubczanski Updated
Comments
Add a comment