eZ Publish REST API v2


Published on


Published in: Technology
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

eZ Publish REST API v2

  1. 1. REST API V2
  2. 2. Agenda
  3. 3. AgendaFirst things first1. What is REST2. eZ publish 5, REST API v23. Client API4. REST server API5. Examples & practice
  4. 4. What is REST ?
  5. 5. What is RESTREST = REpresentational State TransferIdempotent GET will NEVER change dataUses 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. 6. eZ publish 5 REST API
  7. 7. eZ Publish 5 REST APIArchitecture
  8. 8. eZ Publish 5 REST APIImplementation choicesOur REST API provides resourcesThe 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 XWe chose not to implement TONS of resources. KISS. Easier maintenance, usage Allows us to keep elements unique. Makes HTTP caching possibleAPI exceptions are always converted to HTTP errors NotFoundException: 404 UnauthorizedException: 401 RuntimeException: 500...
  9. 9. eZ Publish 5 REST APIAuthenticationAuthentication will be native OAuth 2 Basic SSL client certificateAuthentication 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. 10. eZ Publish 5 REST APIClient / Server communication flow
  11. 11. Client API
  12. 12. Client SDKDeveloper firstWe had two choices : fat server, or fat client. We went with the fat clientThe server is as simple as possibleComplexity 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 structsThe SAME code can be transparently executed locally or remotely !
  13. 13. Server API
  14. 14. Server REST APIResources, verbs and resource linksThe REST API is a thin oneThe amount of resources is purposefully limitedMost resources can be requested with different verbs Each verb will have a different action each action requires a different RequestThe 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. 15. Server SDKAccept headersResources 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 versionThe 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. 16. Server SDKRequest exampleRequestGET / HTTP/1.1Host: api.example.netAccept: application/vnd.ez.api.Root+xmlResponseHTTP/1.1 200 OKContent-Type: application/vnd.ez.api.Root+xmlContent-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. 17. Server SDKHATEOASHypermedia As The Engine Of Application StateA « perfect » REST API should be self sufficientConsumers should be able to crawl the API without knowing thestructureThe root resource lists further resources content list, section list, users, etcFurther resources should ultimately provide more linksNot done yet, but heavily considered
  18. 18. Examples !
  19. 19. Practice time
  20. 20. Practice timeSetupcd /var/www/ezp-nextgit fetchgit stashgit checkout ezscgit clone git://gist.github.com/3658045.git examplescd examples/
  21. 21. The end ?Documentation, specs:http://github.com/ezsystems/ezp-next/tree/master/doc/specifications/rest/ContactTwitter: @bdunogierGoogle+: Bertrand DunogierSlideShare: BertrandDunogier