1. REST & PHP API
eZ Winter Conference 2011, Nice
mandag 31. januar 2011 1

2. Introduction
2
mandag 31. januar 2011 2

3. About me
Ole Marius Smestad
Lead engineer for eZ Publish
oms@ez.no
@dotten
Presenter: Ole Marius Smestad 27.01.2011 3
mandag 31. januar 2011 3

4. Agenda
Presenter: Ole Marius Smestad 27.01.2011 4
mandag 31. januar 2011 4

5. Agenda
News and conceptual feature discussion
Presenter: Ole Marius Smestad 27.01.2011 4
mandag 31. januar 2011 4

6. Agenda
News and conceptual feature discussion
What has been done
Presenter: Ole Marius Smestad 27.01.2011 4
mandag 31. januar 2011 4

7. Agenda
News and conceptual feature discussion
What has been done
What is being delivered
Presenter: Ole Marius Smestad 27.01.2011 4
mandag 31. januar 2011 4

8. Agenda
News and conceptual feature discussion
What has been done
What is being delivered
How to put this work to use
Presenter: Ole Marius Smestad 27.01.2011 4
mandag 31. januar 2011 4

9. Agenda
News and conceptual feature discussion
What has been done
What is being delivered
How to put this work to use
A bit of code
Presenter: Ole Marius Smestad 27.01.2011 4
mandag 31. januar 2011 4

10. A retrospective
5
mandag 31. januar 2011 5

11. A retrospective
APIs
Presenter: Ole Marius Smestad 27.01.2011 6
mandag 31. januar 2011 6

12. A retrospective
PHP
eZ Publish API
REST
Presenter: Ole Marius Smestad 27.01.2011 7
mandag 31. januar 2011 7

13. PHP APIs should be
Simple
Presenter: Ole Marius Smestad 27.01.2011 8
mandag 31. januar 2011 8

14. PHP APIs should be
Simple
Consistent
Presenter: Ole Marius Smestad 27.01.2011 8
mandag 31. januar 2011 8

15. PHP APIs should be
Simple
Consistent
Predictable
Presenter: Ole Marius Smestad 27.01.2011 8
mandag 31. januar 2011 8

16. PHP APIs should be
A clear relationship
Presenter: Ole Marius Smestad 27.01.2011 9
mandag 31. januar 2011 9

17. PHP APIs should be
A clear relationship
Concepts
Objects Tasks
Presenter: Ole Marius Smestad 27.01.2011 9
mandag 31. januar 2011 9

18. PHP APIs should be
Simple
Consistent
Predictable
Presenter: Ole Marius Smestad 27.01.2011 10
mandag 31. januar 2011 10

19. PHP APIs should be
Simple
Consistent
Predictable
A stable point of reference
Presenter: Ole Marius Smestad 27.01.2011 10
mandag 31. januar 2011 10

20. A retrospective
PHP
eZ Publish API
REST
Presenter: Ole Marius Smestad 27.01.2011 11
mandag 31. januar 2011 11

21. A retrospective
REST
Presenter: Ole Marius Smestad 27.01.2011 12
mandag 31. januar 2011 12

22. A retrospective
REST
REST
Presenter: Ole Marius Smestad 27.01.2011 12
mandag 31. januar 2011 12

23. ( )
Presenter: Ole Marius Smestad 27.01.2011 13
mandag 31. januar 2011 13

24. REST
REST as a core feature
Presenter: Ole Marius Smestad 27.01.2011 14
mandag 31. januar 2011 14

25. REST
HTTP is the carrier
Presenter: Ole Marius Smestad 27.01.2011 15
mandag 31. januar 2011 15

26. REST
dedicated front-controller
Presenter: Ole Marius Smestad 27.01.2011 16
mandag 31. januar 2011 16

27. REST
back to the mothership
Presenter: Ole Marius Smestad 27.01.2011 17
mandag 31. januar 2011 17

28. REST
REST setup
REST
eZP
REST
reqest
FC
eZ
Publish
web-­‐request
Presenter: Ole Marius Smestad 27.01.2011 18
mandag 31. januar 2011 18

29. REST
REST setup
REST eZP
FC
Presenter: Ole Marius Smestad 27.01.2011 19
mandag 31. januar 2011 19

30. REST
mapping content into
resources
Presenter: Ole Marius Smestad 27.01.2011 20
mandag 31. januar 2011 20

31. REST
Makes data available
Presenter: Ole Marius Smestad 27.01.2011 21
mandag 31. januar 2011 21

32. REST
Makes data reusable
Presenter: Ole Marius Smestad 27.01.2011 21
mandag 31. januar 2011 21

33. REST
content is liberated
Presenter: Ole Marius Smestad 27.01.2011 22
mandag 31. januar 2011 22

34. One point oh
23
mandag 31. januar 2011 23

35. One point oh
Presenter: Ole Marius Smestad 27.01.2011 24
mandag 31. januar 2011 24

36. One point oh
Being released as a part of Matterhorn
Presenter: Ole Marius Smestad 27.01.2011 24
mandag 31. januar 2011 24

37. One point oh
Being released as a part of Matterhorn
Focus on infrastructure and basics
Presenter: Ole Marius Smestad 27.01.2011 24
mandag 31. januar 2011 24

38. One point oh
Being released as a part of Matterhorn
Focus on infrastructure and basics
Making content accessible (in useful ways)
Presenter: Ole Marius Smestad 27.01.2011 24
mandag 31. januar 2011 24

39. One point oh
Being released as a part of Matterhorn
Focus on infrastructure and basics
Making content accessible (in useful ways)
Always adaptable
Presenter: Ole Marius Smestad 27.01.2011 24
mandag 31. januar 2011 24

40. One point oh
Github repositories
available today
Presenter: Ole Marius Smestad 27.01.2011 25
mandag 31. januar 2011 25

41. One point oh – the fineprint
Presenter: Ole Marius Smestad 27.01.2011 26
mandag 31. januar 2011 26

42. One point oh – the fineprint
Wonʼt support full CRUD in 1.0
Presenter: Ole Marius Smestad 27.01.2011 26
mandag 31. januar 2011 26

43. One point oh – the fineprint
Wonʼt support full CRUD in 1.0
Waiting for additions to our PHP API to fully support this
Presenter: Ole Marius Smestad 27.01.2011 26
mandag 31. januar 2011 26

44. One point oh – the fineprint
Wonʼt support full CRUD in 1.0
Waiting for additions to our PHP API to fully support this
Applies to built-in content resources
Presenter: Ole Marius Smestad 27.01.2011 26
mandag 31. januar 2011 26

45. One point oh – the fineprint
Wonʼt support full CRUD in 1.0
Waiting for additions to our PHP API to fully support this
Applies to built-in content resources
REST extensions will be able to provide all operations from day
one
Presenter: Ole Marius Smestad 27.01.2011 26
mandag 31. januar 2011 26

46. One point oh – the fineprint
Wonʼt support full CRUD in 1.0
Waiting for additions to our PHP API to fully support this
Applies to built-in content resources
REST extensions will be able to provide all operations from day
one
Presenter: Ole Marius Smestad 27.01.2011 26
mandag 31. januar 2011 26

47. Key features
27
mandag 31. januar 2011 27

48. Key features
content resources
Presenter: Ole Marius Smestad 27.01.2011 28
mandag 31. januar 2011 28

49. Getting node data
GET /[api]/ezp/v1/content/⤦
node/<ID> HTTP/1.1
Presenter: Ole Marius Smestad 27.01.2011 29
mandag 31. januar 2011 29

50. Getting node data
Presenter: Ole Marius Smestad 27.01.2011 30
mandag 31. januar 2011 30

51. Getting node data
classIdentifier
objectName
datePublished
dateModified
remoteID
objectRemoteID
nodeID
objectID
Full URL, etc.
Presenter: Ole Marius Smestad 27.01.2011 30
mandag 31. januar 2011 30

52. Getting fields
GET /[api]/ezp/v1/content/⤦
object/<objectId>/fields⤦
HTTP/1.1
Presenter: Ole Marius Smestad 27.01.2011 31
mandag 31. januar 2011 31

53. Getting fields
fields/<fieldname>
type (datatype string)
identifier (attribute identifier)
value (string representation of data)
id (object attribute numerical ID)
classattribute_id (class attribute numerical ID)
Presenter: Ole Marius Smestad 27.01.2011 32
mandag 31. januar 2011 32

54. Getting a specific field
GET /[api]/ezp/v1/content/⤦
object/<objectId>/field/⤦
<FieldIdentifier> HTTP/1.1
Presenter: Ole Marius Smestad 27.01.2011 33
mandag 31. januar 2011 33

55. Key features
Rendered view
Presenter: Ole Marius Smestad 27.01.2011 34
mandag 31. januar 2011 34

56. Key features
Systematic URLs
Response groups
Other resources available
child lists
sorting
Presenter: Ole Marius Smestad 27.01.2011 35
mandag 31. januar 2011 35

57. Extending the REST API
36
mandag 31. januar 2011 36

58. Extending REST
URI pattern
Presenter: Ole Marius Smestad 27.01.2011 37
mandag 31. januar 2011 37

59. URI pattern
Just a token to trigger your rewrite rule
Call +
GET Host / Prefix / Provider / Version / params
ezpRestPrefixFilterInterface
Presenter: Ole Marius Smestad 27.01.2011 38
mandag 31. januar 2011 38

60. URI pattern
Just a token to trigger your rewrite rule
Prefix Provider Version
ezpRestPrefixFilterInterface
Presenter: Ole Marius Smestad 27.01.2011 38
mandag 31. januar 2011 38

61. URI pattern
Prefix Just a token to trigger your rewrite rule
Provider Version
ezpRestPrefixFilterInterface
Presenter: Ole Marius Smestad 27.01.2011 38
mandag 31. januar 2011 38

62. URI pattern
Prefix Just a token to trigger your rewrite rule
Provider Version
ezpRestPrefixFilterInterface
Presenter: Ole Marius Smestad 27.01.2011 38
mandag 31. januar 2011 38

63. URI pattern
Prefix Just a token to trigger your rewrite rule
Provider
ezpRestPrefixFilterInterface
Version
Presenter: Ole Marius Smestad 27.01.2011 38
mandag 31. januar 2011 38

64. URI pattern
Prefix Just a token to trigger your rewrite rule
Provider
ezpRestPrefixFilterInterface
Version
Presenter: Ole Marius Smestad 27.01.2011 38
mandag 31. januar 2011 38

65. URI pattern
Prefix Just a token to trigger your rewrite rule
Provider
ezpRestPrefixFilterInterface
Version
Presenter: Ole Marius Smestad 27.01.2011 38
mandag 31. januar 2011 38

66. Remember, remember
ezpRestPrefixFilterInterface
Presenter: Ole Marius Smestad 27.01.2011 39
mandag 31. januar 2011 39

67. Prefix filter
Always knows
Current provider
Current parsed version value
Presenter: Ole Marius Smestad 27.01.2011 40
mandag 31. januar 2011 40

68. Versioned API
class ezpRestRouter extends ezcMvcRouter
{
public function createRoutes()
{
// ezpRestApiProvider
$routes = array(
new ezcMvcRailsRoute( '/content/node/:nodeId/listAtom', 'ezpRestAtomController', 'collection' ),
new ezcMvcRailsRoute( '/content/node/:nodeId/list', 'ezpRestContentController', 'list' ),
new ezcMvcRailsRoute( '/content/node/:nodeId', 'ezpRestContentController', 'viewContent' ),
new ezcMvcRailsRoute( '/content/node/:nodeId/fields', 'ezpRestContentController', 'viewFields' ),
new ezcMvcRailsRoute( '/content/node/:nodeId/field/:fieldIdentifier', 'ezpRestContentController', 'viewFie
new ezcMvcRailsRoute( '/content/object/:objectId', 'ezpRestContentController', 'viewContent' ),
new ezcMvcRailsRoute( '/content/object/:objectId/fields', 'ezpRestContentController', 'viewFields' ),
new ezcMvcRailsRoute( '/content/object/:objectId/field/:fieldIdentifier', 'ezpRestContentController', 'vie
new ezpRestVersionedRoute( new ezcMvcRailsRoute( '/foo', 'myController', 'myActionOne' ), 1 ),
new ezpRestVersionedRoute( new ezcMvcRailsRoute( 'e/foo', 'myController2 or myControlerWhichExtendsmyContr
'myBetterAndScalingAction' ), 2 ),
);
return ezcMvcRouter::prefix( '/api', $routes );
}
}
Presenter: Ole Marius Smestad 27.01.2011 41
mandag 31. januar 2011 41

69. Versioned API
ezpRestVersionedRoute
Presenter: Ole Marius Smestad 27.01.2011 42
mandag 31. januar 2011 42

70. Versioned API
Version
makes the notion version a
part of the routing decision
Presenter: Ole Marius Smestad 27.01.2011 43
mandag 31. januar 2011 43

71. Extending the interface
REST providers
Presenter: Ole Marius Smestad 27.01.2011 44
mandag 31. januar 2011 44

72. Extending the interface
ezpRestProviderInterface
Presenter: Ole Marius Smestad 27.01.2011 45
mandag 31. januar 2011 45

73. Extending the REST interface
Overview of hooks
Presenter: Ole Marius Smestad 27.01.2011 46
mandag 31. januar 2011 46

74. Presenter: Ole Marius Smestad 27.01.2011 47
mandag 31. januar 2011 47

75. Route setup 1
class ezpRestRouter extends ezcMvcRouter
{
public function createRoutes()
{
// ezpRestApiProvider
$routes = array(
new ezcMvcRailsRoute( '/content/node/:nodeId/listAtom', 'ezpRestAtomController', 'collection' ),
new ezcMvcRailsRoute( '/content/node/:nodeId/list', 'ezpRestContentController', 'list' ),
new ezcMvcRailsRoute( '/content/node/:nodeId', 'ezpRestContentController', 'viewContent' ),
new ezcMvcRailsRoute( '/content/node/:nodeId/fields', 'ezpRestContentController', 'viewFields' ),
new ezcMvcRailsRoute( '/content/node/:nodeId/field/:fieldIdentifier', 'ezpRestContentController', 'viewFie
new ezcMvcRailsRoute( '/content/object/:objectId', 'ezpRestContentController', 'viewContent' ),
new ezcMvcRailsRoute( '/content/object/:objectId/fields', 'ezpRestContentController', 'viewFields' ),
new ezcMvcRailsRoute( '/content/object/:objectId/field/:fieldIdentifier', 'ezpRestContentController', 'vie
new ezpRestVersionedRoute( new ezcMvcRailsRoute( '/foo', 'myController', 'myActionOne' ), 1 ),
new ezpRestVersionedRoute( new ezcMvcRailsRoute( 'e/foo', 'myController2 or myControlerWhichExtendsmyContr
'myBetterAndScalingAction' ), 2 ),
);
return ezcMvcRouter::prefix( '/api', $routes );
}
}
Presenter: Ole Marius Smestad 27.01.2011 48
mandag 31. januar 2011 48

76. Route setup 2
class ezpRestRouter extends ezcMvcRouter
{
public function createRoutes()
{
$providerRoutes = ezpRestProvider::getProvider( ezpRestPrefixFilterInterface::getApiProviderName() )-
>getRoutes();
$routes = array(
new ezpMvcRailsRoute( '/fatal', 'ezpRestErrorController', 'show' ),
new ezpMvcRailsRoute( '/http-basic-auth', 'ezpRestAuthController', 'basicAuth' ),
new ezpMvcRailsRoute( '/login/oauth', 'ezpRestAuthController', 'oauthRequired' ),
new ezpMvcRailsRoute( '/oauth/token', 'ezpRestOauthTokenController', 'handleRequest'),
// ezpRestVersionedRoute( $route, $version )
// $version == 1 should be the same as if the only the $route had been present
new ezpRestVersionedRoute( new ezpMvcRailsRoute( '/foo', 'myController', 'myActionOne' ), 1 ),
new ezpRestVersionedRoute( new ezpMvcRailsRoute( '/foo', 'myController', 'myActionOneBetter' ),
2 ),
);
return ezcMvcRouter::prefix( '/api', array_merge( $providerRoutes, $routes ) );
}
}
Presenter: Ole Marius Smestad 27.01.2011 49
mandag 31. januar 2011 49

77. Protecting your resources
50
mandag 31. januar 2011 50

78. Authentication
OAuth 2.0
Presenter: Ole Marius Smestad 27.01.2011 51
mandag 31. januar 2011 51

79. Authentication
Basic auth
Presenter: Ole Marius Smestad 27.01.2011 52
mandag 31. januar 2011 52

80. Other security related options
Require HTTPS (a requirement of OAuth)
Decide which auth filter to use
Presenter: Ole Marius Smestad 27.01.2011 53
mandag 31. januar 2011 53

81. Summary
54
mandag 31. januar 2011 54

82. Summary
Presenter: Ole Marius Smestad 27.01.2011 55
mandag 31. januar 2011 55

83. Summary
Comes with the next release
Presenter: Ole Marius Smestad 27.01.2011 55
mandag 31. januar 2011 55

84. Summary
Comes with the next release
Gives access to existing content in a systematic way
Presenter: Ole Marius Smestad 27.01.2011 55
mandag 31. januar 2011 55

85. Summary
Comes with the next release
Gives access to existing content in a systematic way
Output of content can be tweaked
Presenter: Ole Marius Smestad 27.01.2011 55
mandag 31. januar 2011 55

86. Summary
Comes with the next release
Gives access to existing content in a systematic way
Output of content can be tweaked
Is extendible through eZ Market extensions
Presenter: Ole Marius Smestad 27.01.2011 55
mandag 31. januar 2011 55

87. Summary
Comes with the next release
Gives access to existing content in a systematic way
Output of content can be tweaked
Is extendible through eZ Market extensions
API is versioned
Presenter: Ole Marius Smestad 27.01.2011 55
mandag 31. januar 2011 55

88. Summary
Comes with the next release
Gives access to existing content in a systematic way
Output of content can be tweaked
Is extendible through eZ Market extensions
API is versioned
Control of BC
Presenter: Ole Marius Smestad 27.01.2011 55
mandag 31. januar 2011 55

89. Summary
Comes with the next release
Gives access to existing content in a systematic way
Output of content can be tweaked
Is extendible through eZ Market extensions
API is versioned
Control of BC
Control of already rolled out API clients
Presenter: Ole Marius Smestad 27.01.2011 55
mandag 31. januar 2011 55

90. Questions?
Presenter: Ole Marius Smestad 27.01.2011 56
mandag 31. januar 2011 56

91. Possibility for more Q&A
at the barcamp
Presenter: Ole Marius Smestad 27.01.2011 57
mandag 31. januar 2011 57

92. The end
Thank you for listening
Presenter: Ole Marius Smestad 27.01.2011 58
mandag 31. januar 2011 58

93. The end
github.com/ezsystems/ezp_rest
Presenter: Ole Marius Smestad 27.01.2011 59
mandag 31. januar 2011 59