This document provides an overview of a REST API V2. It discusses what REST is, the eZ Publish 5 REST API architecture and implementation choices, authentication methods, and the client/server communication flow. Examples of requests and responses are also presented to demonstrate the resources, verbs, and HATEOAS principles used in the API.

1. REST API V2

2. Agenda

3. Agenda
First things first
1. What is REST
2. eZ publish 5, REST API v2
3. Client API
4. REST server API
5. Examples & practice

4. What is REST ?

5. 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

6. eZ publish 5 REST API

7. eZ Publish 5 REST API
Architecture

8. eZ Publish 5 REST API
Implementation choices
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...

9. eZ Publish 5 REST API
Authentication
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

10. eZ Publish 5 REST API
Client / Server communication flow

11. Client API

12. Client SDK
Developer first
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 !

13. Server API

14. Server REST API
Resources, verbs and resource links
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

15. Server SDK
Accept headers
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

16. Server SDK
Request example
Request
GET / 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>

17. Server SDK
HATEOAS
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

18. Examples !

19. Practice time

20. Practice time
Setup
cd /var/www/ezp-next
git fetch
git stash
git checkout ezsc
git clone git://gist.github.com/3658045.git examples
cd examples/

21. The end
?
Documentation, specs:
http://github.com/ezsystems/ezp-next/tree/master/doc/specifications/rest/
Contact
Twitter: @bdunogier
Google+: Bertrand Dunogier
SlideShare: BertrandDunogier