Upload
bertrand-dunogier
View
3.141
Download
3
Embed Size (px)
DESCRIPTION
Present
Citation preview
REST API V2
Agenda
AgendaFirst things first
1. What is REST
2. eZ publish 5, REST API v2
3. Client API
4. REST server API
5. Examples & practice
What is REST ?
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
eZ publish 5 REST API
eZ Publish 5 REST APIArchitecture
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
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
eZ Publish 5 REST APIClient / Server communication flow
Client API
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
Server API
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
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
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
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
Examples !
Practice time
Practice time
cd /var/www/ezp-nextgit fetchgit stashgit checkout ezsc
git clone git://gist.github.com/3658045.git examplescd examples/
Setup
The end
?Documentation, specs:http://github.com/ezsystems/ezp-next/tree/master/doc/specifications/rest/
Contact
Twitter: @bdunogierGoogle+: Bertrand DunogierSlideShare: BertrandDunogier