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
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...
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
eZ Publish 5 REST APIClient / Server communication flow
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
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
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