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