ez publish rest api v2
DESCRIPTION
PresentTRANSCRIPT
![Page 1: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/1.jpg)
REST API V2
![Page 2: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/2.jpg)
Agenda
![Page 3: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/3.jpg)
AgendaFirst things first
1. What is REST
2. eZ publish 5, REST API v2
3. Client API
4. REST server API
5. Examples & practice
![Page 4: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/4.jpg)
What is REST ?
![Page 5: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/5.jpg)
What is REST
REST = REpresentational State Transfer
Idempotent GET will NEVER change data
Uses HTTP verbs Well known ones: GET, POST More discrete ones: PUT, DELETE Exotic one: PATCH. But it has an RFC. I swear.
Safe GET is safe PUT, DELETE are not (especially DELETE). POST usually is not.
CRUD support Create, Retrieve, Update, Delete
![Page 6: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/6.jpg)
eZ publish 5 REST API
![Page 7: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/7.jpg)
eZ Publish 5 REST APIArchitecture
![Page 8: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/8.jpg)
eZ Publish 5 REST API
Our REST API provides resources
The same resource has different uses depending on the VERB GET /content/objects : lists objects POST /content/objects: creates a new object DELETE /content/objects/x: deletes object X PATCH /content/objects/x: modifies object X
We chose not to implement TONS of resources. KISS. Easier maintenance, usage Allows us to keep elements unique. Makes HTTP caching possible
API exceptions are always converted to HTTP errors NotFoundException: 404 UnauthorizedException: 401 RuntimeException: 500...
Implementation choices
![Page 9: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/9.jpg)
eZ Publish 5 REST API
Authentication will be native OAuth 2 Basic SSL client certificate
Authentication has a direct impact on the results Each authenticated (or anonymous) user may get different results This is of course based on the eZ Publish users, roles & policies
Authentication
![Page 10: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/10.jpg)
eZ Publish 5 REST APIClient / Server communication flow
![Page 11: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/11.jpg)
Client API
![Page 12: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/12.jpg)
Client SDK
We had two choices : fat server, or fat client. We went with the fat client
The server is as simple as possible
Complexity lies in the client SDK, which we do provide At least a PHP client SDK Maybe a Javascript SDK. Feel like doing a pull request ? ;-) In an ideal world, Android, iOS...
The client SDK mirrors the Public API Public API services, with methods Value Objects Create & Update structs
The SAME code can be transparently executed locally or remotely !
Developer first
![Page 13: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/13.jpg)
Server API
![Page 14: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/14.jpg)
Server REST API
The REST API is a thin one
The amount of resources is purposefully limited
Most resources can be requested with different verbs Each verb will have a different action each action requires a different Request
The root resource (/) will list the available root resources This makes the API self-aware It makes evolution easier, by limit the hard coding in client implementations
Resources, verbs and resource links
![Page 15: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/15.jpg)
Server SDK
Resources Responses also depend on the Accept Request header
Example on GET /content/objects/1
Accept: application/vnd.ez.api.Content To request a full content, including current version
Accept: application/vnd.ez.api.ContentInfo To request a content info, without current version
The Response format also depends on the Accept header
Accept: application/vnd.ez.api.Content+xml To request an XML Response
Accept: application/vnd.ez.api.Content+json To request a JSON Response
Accept headers
![Page 16: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/16.jpg)
Server SDK
RequestGET / HTTP/1.1
Host: api.example.net
Accept: application/vnd.ez.api.Root+xml
Response
HTTP/1.1 200 OK
Content-Type: application/vnd.ez.api.Root+xml
Content-Length: xxx
<?xml version="1.0" encoding="UTF-8"?>
<Root>
<content href="/content/objects" media-type="application/vnd.ez.api.ContentInfoList+xml"/>
<contentTypes href="/content/types" media-type="application/vnd.ez.api.ContentTypeInfoList+xml"/>
<users href="/user/users" media-type="application/vnd.ez.api.UserRefList+xml"/>
<roles href="/user/roles" media-type="application/vnd.ez.api.RoleList+xml"/>
<rootLocation href="/content/locations/1" media-type="application/vnd.ez.api.Location+xml"/>
<rootUserGroup href="/user/groups/1/3" media-type="application/vnd.ez.api.UserGroup+xml"/>
<rootMediaFolder href="/content/locations/1/43" media-type="application/vnd.ez.api.Location+xml"/>
<trash href="/content/trash" media-type="application/vnd.ez.api.LocationList+xml"/>
<sections href="/content/sections" media-type="application/vnd.ez.api.SectionList+xml"/>
<views href="/content/views" media-type="application/vnd.ez.api.RefList+xml"/>
</Root>
Request example
![Page 17: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/17.jpg)
Server SDK
Hypermedia As The Engine Of Application State
A « perfect » REST API should be self sufficient
Consumers should be able to crawl the API without knowing the structure
The root resource lists further resources content list, section list, users, etc
Further resources should ultimately provide more links
Not done yet, but heavily considered
HATEOAS
![Page 18: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/18.jpg)
Examples !
![Page 19: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/19.jpg)
Practice time
![Page 20: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/20.jpg)
Practice time
cd /var/www/ezp-nextgit fetchgit stashgit checkout ezsc
git clone git://gist.github.com/3658045.git examplescd examples/
Setup
![Page 21: eZ Publish REST API v2](https://reader037.vdocuments.mx/reader037/viewer/2022102705/54827e19b4af9f9b538b4abb/html5/thumbnails/21.jpg)
The end
?Documentation, specs:http://github.com/ezsystems/ezp-next/tree/master/doc/specifications/rest/
Contact
Twitter: @bdunogierGoogle+: Bertrand DunogierSlideShare: BertrandDunogier