The document discusses various application programming interfaces (APIs) for interacting with eZ Platform's content repository, including the public PHP API, REST API, and a GraphQL prototype. It provides examples of using the public API and REST API to retrieve content, create sessions, and perform searches. It also outlines future plans to improve the REST API and develop a new REST v3 API based on the Symfony API Platform project.

1. Using eZ Platform in an API eraUsing eZ Platform in an API era
The time for monolithic applications is far gone. Now developers are
building solutions by assembling applications and services of all kinds and in
all ways.
We'll show you how eZ Platform embraces the modern way of building
applications by interacting with its Content Repository using
Public (PHP) API, REST API and GraphQL.
rtrand Dunogier
ps://github.com/bdunogier
ps://twitter.com/bdunogier
Andrew Lo
https://github.com/alo
https://twitter.com/andrew_

2. Public APIPublic API
How and why use it, BCHow and why use it, BC
promise explainedpromise explained

3. What is an API?What is an API?
API - Application Programming Interface - is a set of
well defined and maintained methods for building
application software.
eZ Platform Public API:eZ Platform Public API:
is a PHP API, grouped into Services with methods,
allowing Content Repository manipulation,
is provided by ezpublish-kernel package via
the interfaces in eZPublishAPI PHP
namespace.

4. What belongs to eZ Platform APIWhat belongs to eZ Platform API
Repository Services defined by interfaces in the
eZPublishAPIRepository namespace.
Value Objects defined in the
eZPublishAPIRepositoryValues
namespace.
Other interfaces defined in the
eZPublishAPIRepository namespace.

5. What does NOT belong toWhat does NOT belong to
eZ Platform APIeZ Platform API
Twig templates.
Database schema (though there is still a separate
BC promise for that).
Anything located in eZPublishCore
namespace.

6. Available Repository Services:Available Repository Services:
- Content Service.
- Location Service.
- Content Service.
- Permission Resolver.
- Field Type Service.
- Language Service.
- Object State Service.
- Role Service.
- Search Service.
- Section Service.
- Trash Service.
- URL Service
- URL Alias Service.
- User Service.
- Bookmark Service.

7. Accessing Public API ServicesAccessing Public API Services
Getting Content Service:
in a Symfony Container-aware class:
in a Controller extending
eZBundleEzPublishCoreBundleControlle
(not recommended):
/** @var SymfonyComponentDependencyInjectionContainerInterface
$repository = $container->get('ezpublish.api.repository');
/** @var eZPublishAPIRepositoryContentService $contentService
$contentService = $repository->getContentService();
/** @var eZPublishAPIRepositoryContentService $contentService
$contentService = $this->getRepository()->getContentService();

8. Getting Content Service:
via Repository injected into Symfony service:
by injecting specific Repository service definition:
AppMyService:
- '@ezpublish.api.repository'
AppMyService:
- '@ezpublish.api.service.content'

9. Why use an API?Why use an API?
Any changes to application state (mostly database
operations changing state of Content) are
maintained and supported.
It ensures all necessary layers (e.g. cache) are
properly handled by the Content Framework.
Has a Backward Compatiblity promise on usage
(for a Consumer).

10. Semantic VersioningSemantic Versioning
eZ Platform packages, including
ezpublish-kernel follow the SemVer version
numbering convention:
X.Y.Z (e.g. 2.1.1)
where:
X is major version (release).
Y is minor version.
Z is patch version.
For more information see .https://semver.org/

11. BC promise (X.Y.Z)BC promise (X.Y.Z)
Backward Compatibility promise is related mostly to
changes between minor (Y) versions.
Any minor release Y will not break existing code
written for major version X.

12. eZ Platform APIeZ Platform API
We ensure that any usage of API from the Consumer
point of view will work across any minor (Y) release.
composer.json:
{
"require": {
"ezsystems/ezpublish-kernel": "^7.1"
}
}

13. Examples of BC guaranteedExamples of BC guaranteed
usages:usages:
Backward Compatibility is guaranteed for:
class MyService
{
/** @var eZPublishAPIRepositoryContentService */
private $contentService;
public function doSomething()
{
// ...
$this->contentService->publishVersion($versionInfo);
// ...
}
}

14. Sometimes there is no other way than to use code
for which there is no BC guarantee.
What to do?
Unit-Test it!

15. Unit testing custom unsupported implementationsUnit testing custom unsupported implementations
composer.json:
{
"require": {
"ezsystems/ezpublish-kernel": "^7.1@dev"
}
}
use PHPUnitFrameworkTestCase;
use eZPublishCoreSomething;
class ClassUsingSomethingTest extends TestCase
{
public function testSomething()
{
$class = new MyClassUsingSomething();
// ...
$class->doSomething();
// ...
}
}

16. REST APIREST API
verbs, media types,verbs, media types,
response formatsresponse formats

17. REST APIREST API
Remote API implemented over HTTP protocol.
Reflects Public (PHP) API
Allows manipulating eZ Platform: Content, Content
Types, Locations, Content Relations, Object States,
URL aliases, Users and their permissions (Roles
and policies).
Exposes Search Service (via /views endpoint).
Uses Repository permissions (by default every
request is done as Anonymous user).
Is NOT SiteAccess-aware.

18. DocumentationDocumentation
Currently available at:
Will be moved to the Developer Documentation
( )
https://github.com/ezsystems/ezpublish-
kernel/blob/v7.1.1/doc/specifications/rest/REST-
API-V2.rst
http://doc.ezplatform.com

19. REST API:REST API:
is available for every eZ Platform installation at the
prefix /api/ezp/v2,
supports HTTP methods (verbs):
GET,
POST,
COPY,
PATCH,
DELETE,
PUBLISH,
OPTIONS.

20. allows to use X-Http-Method-override header
if a web server doesn't allow all mentioned
methods,
supports uniformly XML and JSON request
payloads and responses.
Expects in most cases HTTP headers:
Cookie,
X-CSRF-Token (for requests modifying state of
the system),
Accepts (with expected by a client media type
and format) - to control output,
Content-Type (with provided by a client media
type and format) - to control input.

21. X Siteaccess (to provide SiteAccess name, if
needed).

22. The Simplest REST API HTTP requestThe Simplest REST API HTTP request
returns Root response:
GET /api/ezp/v2 HTTP/1.1
Host: www.example.net

23. <?xml version="1.0" encoding="UTF-8"?>
<Root media-type="application/vnd.ez.api.Root+xml">
<content media-type="" href="/api/ezp/v2/content/objects"/>
<contentByRemoteId media-type="" href="/api/ezp/v2/content/ob
<contentTypes media-type="application/vnd.ez.api.ContentTypeI
<contentTypeByIdentifier media-type="" href="/api/ezp/v2/cont
<contentTypeGroups media-type="application/vnd.ez.api.Content
<contentTypeGroupByIdentifier media-type="" href="/api/ezp/v2
<users media-type="application/vnd.ez.api.UserRefList+xml" hr
<usersByRoleId media-type="application/vnd.ez.api.UserRefList
<usersByRemoteId media-type="application/vnd.ez.api.UserRefLi
<usersByEmail media-type="application/vnd.ez.api.UserRefList+x
<usersByLogin media-type="application/vnd.ez.api.UserRefList+x
<roles media-type="application/vnd.ez.api.RoleList+xml" href=
<rootLocation media-type="application/vnd.ez.api.Location+xml
<rootUserGroup media-type="application/vnd ez api UserGroup+xm

24. Creating REST sessionCreating REST session
Request:
POST /user/sessions HTTP/1.1
Host: www.example.net
Accept: application/vnd.ez.api.Session+xml
Content-Type: application/vnd.ez.api.SessionInput+xml
<?xml version="1.0" encoding="UTF-8"?>
<SessionInput>
<login>admin</login>
<password>secret</password>
</SessionInput>

25. Response:
HTTP/1.1 201 Created
Location: /user/sessions/go327ij2cirpo59pb6rrv2a4el2
Set-Cookie: eZSSID=go327ij2cirpo59pb6rrv2a4el2; domain=.example.n
Content-Type: application/vnd.ez.api.Session+xml
<?xml version="1.0" encoding="UTF-8"?>
<Session href="/user/sessions/sessionID" media-type="application/v
<name>eZSSID</name>
<identifier>go327ij2cirpo59pb6rrv2a4el2</identifier>
<csrfToken>23lkneri34ijajedfw39orj3j93</csrfToken>
<User href="/user/users/14" media-type="vnd.ez.api.User+xml"/>
</Session>

26. Creating REST session with mixedCreating REST session with mixed
input and output formatsinput and output formats
Request:
POST /user/sessions HTTP/1.1
Host: www.example.net
Accept: application/vnd.ez.api.Session+json
Content-Type: application/vnd.ez.api.SessionInput+xml
<?xml version="1.0" encoding="UTF-8"?>
<SessionInput>
<login>admin</login>
<password>secret</password>
</SessionInput>

27. Response:
HTTP/1.1 201 Created
Location: /user/sessions/go327ij2cirpo59pb6rrv2a4el2
Set-Cookie: eZSSID=go327ij2cirpo59pb6rrv2a4el2; domain=.example.n
Content-Type: application/vnd.ez.api.Session+json
{
"Session": {
"name": "eZSSID",
"identifier": "go327ij2cirpo59pb6rrv2a4el2",
"csrfToken": "23lkneri34ijajedfw39orj3j93",
"User": {
"_href": "/user/users/14",
"_media-type": "application/vnd.ez.api.User+json"
}
}
}

28. Search Service exampleSearch Service example
search Service expects Criterions, which makes
request complicated,
hence, it requires POST and that implies it requires
X-CSRF-Token header also.

29. Request:
POST /api/ezp/v2/views HTTP/1.1
Host: www.example.net
Content-Type: application/vnd.ez.api.ViewInput+xml; version=1.1
Accept: application/vnd.ez.api.Version+json
{
"ViewInput": {
"identifier": "my-unique-identifier",
"public": false,
"LocationQuery": {
"Criteria": {},
"FacetBuilders": {},
"SortClauses": {
"LocationPriority": "ascending"
},
"Filter": {

30. Response:
{
"View": {
"_media-type": "application/vnd.ez.api.View+json",
"_href": "/api/ezp/v2/views/subitems-load-location-2",
"identifier": "subitems-load-location-2",
"Query": {
"_media-type": "application/vnd.ez.api.Query+json"
},
"Result": {
"_media-type": "application/vnd.ez.api.ViewResult+jso
"_href": "/api/ezp/v2/views/subitems-load-location-2/
"count": 20,
"time": 0.0048329830169677734,
"timedOut": false,
"maxScore": null,
"searchHits": {

31. Platform REST APIPlatform REST API
Present, time anomaliesPresent, time anomalies
and futureand future

32. Past & presentPast & present
REST API has not been our focus since 1.0.
Stabilizing
Catching up on missing features
v2 won't receive significant improvements

33. Time anomaliesTime anomalies
GraphQL prototypeGraphQL prototype

34. GraphQL primerGraphQL primer
Query language created by Facebook
Strongly typed
Allows you to get exactly what you query
Reduces number of queries, a defect of the v2
REST API

35. {
hero {
name
# Queries can have comments!
friends {
name
}
}
}

36. {
"data": {
"hero":
{
"name": "R2-D2",
"friends": [
{
"name": "Luke Skywalker"
},
{
"name": "Leia Organa"
}
]
}
}
}

37. The prototypeThe prototype
Based on and
.
bdunogier/ezplatform-graphql-bundle
webonyx/graphql-php
overblog/graphqlbundle

38. Is it good ?Is it good ?

39. Yes.Yes.

40. More ?More ?
Surprisingly easy to implement
Great usability
List all content types, with field definitions and
types
Types can be inspected when browsing
Browsing content is really convenient

42. Flexible FieldTypeFlexible FieldType
GraphQL Interfaces ... on InterfaceName {
InterfaceSpecificField }
Interface per fieldtype
Variations of an image
Converted richtext
Direct access to relations
Geo coordinates from location

44. Fitting YOUR content modelFitting YOUR content model
We could go even further:
{
contentModel {
article {
name { text }
intro { html5 }
}
place {
name { text }
location { address latitude longitude }
}
}
}

45. (one last time)

46. LimitationsLimitations
Limited to reading, no writing (mutations)
Not adapted to managing content
Can apply to lightweight application use-cases
comments
ratings
Not optimised

47. FutureFuture
Rework will have to happen one day

48. REST V3: API Platform ?REST V3: API Platform ?

49. Centered around entities and operations on those
Our entities are value objects
Uses Symfony Serialization

50. Very well maintained
Modern formats, HATOAS
GraphQL (using webonyx)
Schema.org
Dynamically self-documented (Swagger/OpenAPI)
Built to be re-used by your own code

51. Slides are available at:
https://alongosz.github.io/ezconf2018-api/