Me
- eZ Community member since 2005
- Part of the eZ Engineering team since 2011
- Lead engineer User Interface at eZ
REST API ?
- REpresentational State Transfer
- In short terms for eZ Publish, an API over HTTP
- Manipulate resources (~URI) with HTTP verbs
- Get the result through the HTTP response
- so knowing HTTP is important (RFC 2616)
HTTP 1.1 Request
- HTTP verb / method :
GET, POST, PUT, DELETE, TRACEOPTIONSHEAD
- ... or a custom verb:
PATCH, COPY, ...
- Set of headers
- a body in
POST, PUT or custom verb requests
HTTP 1.1 Response
- status code (by @stevelosh)
- 1XX: hold on
- 2XX: here you go
- 3XX: go away
- 4XX: you f★★★★d up
- 5XX: I f★★★★d up
- Set of headers
- a body depending on the response
REST API in eZ Publish 4.x
- eZ Publish 4.x has a REST API
- Prefix
/ezp/api/v1/
- Read only
- Very limited scope / incomplete
REST API in eZ Publish 5
- Read / write
- Prefix
/ezp/api/v2/
- Allows to handle almost everything in the repository (Content, Location, Types, ...)
- Support Basic Auth and Session Auth
- XML or JSON support in input and output
- Hypermedia as the Engine of Application State (HATEOAS)
- Specifications: http://j.mp/ezpublish-rest-spec
Auth configuration
- ezpublish/config/security.yml
- HTTP Auth by default
ezpublish_rest:
pattern: ^/api/ezp/v2
stateless: true
ezpublish_http_basic:
realm: eZ Publish REST API
- To switch to session auth, just comment out this block
Session Auth
- Authentication done with a POST on
/user/sessions
201 Created in case of success- Returns the CSRF Token
X-CSRF-Token header required for non safe methods
- POST
- PUT
- DELETE
- custom HTTP verb
Session Auth request
POST /api/ezp/v2/user/sessions HTTP/1.1
Host: ezpublish.ezsc
Content-Type: application/vnd.ez.api.SessionInput+json
Accept: application/vnd.ez.api.Session+json
{
"SessionInput": {
"login": "admin",
"password": "ezsc"
}
}
Session Auth response
HTTP/1.1 201 Created
Date: Wed, 04 Sep 2013 08:29:57 GMT
Set-Cookie: eZSESSID=0ka4636cvs245lr6t6csgroto2; path=/
Status: 201 Created
Location: /api/ezp/v2/user/sessions/0ka4636cvs245lr6t6csgroto2
Set-Cookie: is_logged_in=true; path=/
Content-Type: application/vnd.ez.api.Session+json
{
"Session":{
"_media-type":"application\/vnd.ez.api.Session+json",
"_href":"\/api\/ezp\/v2\/user\/sessions\/0ka4636cvs245lr6t6csgroto2",
"name":"eZSESSID",
"identifier":"0ka4636cvs245lr6t6csgroto2",
"csrfToken":"c66dd36f4ced781c57b1e8407b16a507fb65272e",
"User":{
"_media-type":"application\/vnd.ez.api.User+json",
"_href":"\/api\/ezp\/v2\/user\/users\/14"
}
}
}
HATEOAS
- Never build URIs client side
- Follow links provided by a previous response
- Need to request to root first
- Good for backward compatibility (no hardcoded URIs)
XML or JSON
- Both supported
- Represent the exact same thing
- XML is the base format
- Conversion to JSON with syntax rules
- Example with the root structure
XML Root struct
<?xml version="1.0" encoding="UTF-8"?>
<Root media-type="application/vnd.ez.api.Root+xml">
<content media-type="" href="/api/ezp/v2/content/objects"/>
<contentTypes media-type="application/vnd.ez.api.ContentTypeInfoList+xml" href="/api/ezp/v2/content/types"/>
<users media-type="application/vnd.ez.api.UserRefList+xml" href="/api/ezp/v2/user/users"/>
<roles media-type="application/vnd.ez.api.RoleList+xml" href="/api/ezp/v2/user/roles"/>
<rootLocation media-type="application/vnd.ez.api.Location+xml" href="/api/ezp/v2/content/locations//1/2"/>
<rootUserGroup media-type="application/vnd.ez.api.UserGroup+xml" href="/api/ezp/v2/user/groups//1/5"/>
<rootMediaFolder media-type="application/vnd.ez.api.Location+xml" href="/api/ezp/v2/content/locations//1/43"/>
<trash media-type="application/vnd.ez.api.Trash+xml" href="/api/ezp/v2/content/trash"/>
<sections media-type="application/vnd.ez.api.SectionList+xml" href="/api/ezp/v2/content/sections"/>
<views media-type="application/vnd.ez.api.RefList+xml" href="/api/ezp/v2/content/views"/>
</Root>
JSON Root struct
{
"Root": {
"_media-type": "application/vnd.ez.api.Root+json",
"roles": {"_href": "/api/ezp/v2/user/roles", "_media-type": "application/vnd.ez.api.RoleList+json"},
"content": {"_href": "/api/ezp/v2/content/objects", "_media-type": ""},
"users": {"_href": "/api/ezp/v2/user/users", "_media-type": "application/vnd.ez.api.UserRefList+json"},
"rootLocation": {"_href": "/api/ezp/v2/content/locations//1/2", "_media-type": "application/vnd.ez.api.Location+json"},
"contentTypes": {"_href": "/api/ezp/v2/content/types", "_media-type": "application/vnd.ez.api.ContentTypeInfoList+json"},
"views": {"_href": "/api/ezp/v2/content/views","_media-type": "application/vnd.ez.api.RefList+json"},
"trash": {"_href": "/api/ezp/v2/content/trash", "_media-type": "application/vnd.ez.api.Trash+json"},
"rootUserGroup": {"_href": "/api/ezp/v2/user/groups//1/5", "_media-type": "application/vnd.ez.api.UserGroup+json"},
"rootMediaFolder": {"_href": "/api/ezp/v2/content/locations//1/43", "_media-type": "application/vnd.ez.api.Location+json"},
"sections": {"_href": "/api/ezp/v2/content/sections", "_media-type": "application/vnd.ez.api.SectionList+json"}
}
}
XML or JSON
- The type of output is specified in the
Accept header
application/vnd.ez.api.Content+xmlapplication/vnd.ez.api.Content+jsonapplication/json works too!
- The type of input (if any) is specified in the
Content-Type header
application/vnd.ez.api.ContentCreate+jsonapplication/vnd.ez.api.ContentCreate+xml
Hands on!
Hands on!
- Command line with cURL
- Get the root structure in XML and JSON
- Display locations under the root location
- Read the content and the content info of one of those location
- Delete a content
- Try to delete a content with a user without the required policies
- Create an image content
- Publish the image content
- Bonus: do the same with the Session Auth
Hands on!
EzSystems/EzSummerCampRestApiBundle- Uses the eZ Publish JavaScript REST client:
https://github.com/ezsystems/ez-js-rest-client
- build a very rough admin interface available at
/summercamp/rest-test
- display details of a content
- navigate in contents
- delete a content
- Bonus: copy/move...
The end
?
