Presentation from eZ UnConference #2 about Apigee Console & eZ Publish REST.

1. eZ Publish REST v2 calls made easy
Apigee Console & eZ Publish REST

2. 06/06/2013Presenter: Łukasz Serwatka Slide 2
APIGEE console & eZ Publish REST
Presenter
Łukasz Serwatka
Product Management Technical Lead
lukasz.serwatka@ez.no
@lserwatka
 Working with eZ since 1st of March 2005
 Over 10 years of experience with eZ Publish
 Former member of the Engineering team, now in the Product Management
 eZ Publish & Polish PHP Community Member
 Expert in the mobile solutions (mobile applications & mobile strategies)

3. 06/06/2013Presenter: Łukasz Serwatka Slide 3
APIGEE console & eZ Publish REST
Console To-Go
 The Apigee “eZ Publish” API console makes it easy to learn, test, and debug
the eZ Publish REST v2 API with interactive tools and documentation.

4. 06/06/2013Presenter: Łukasz Serwatka Slide 4
APIGEE console & eZ Publish REST
API Providers

5. 06/06/2013Presenter: Łukasz Serwatka Slide 5
APIGEE console & eZ Publish REST
Console To-Go
 Apigee Console To-Go describes the API using the Web Application
Description Language (WADL). By uploading API description to Apigee a new
custom Console can be created that allows to customize the look and feel,
and then embed API Console on your own developer portal.
 Console can display all methods available to developers, organized into the
groups. Developers can browse the methods, reading the descriptions
provided for each method and parameter, and see what information is
required for each request, what authentication mechanisms are supported,
and what parameters are optional or required. More importantly, developers
can use the Console to enter authentication credentials and easily test
requests and see what responses are returned.

6. 06/06/2013Presenter: Łukasz Serwatka Slide 6
APIGEE console & eZ Publish REST
Console To-Go: Name Your Console
 Visit https://apigee.com/togo to setup a new console

7. 06/06/2013Presenter: Łukasz Serwatka Slide 7
APIGEE console & eZ Publish REST
Console To-Go: Set Credentials

8. 06/06/2013Presenter: Łukasz Serwatka Slide 8
APIGEE console & eZ Publish REST
Console To-Go: Describe Your API

9. 06/06/2013Presenter: Łukasz Serwatka Slide 9
APIGEE console & eZ Publish REST
What is WADL?
 The Web Application Description Language (WADL) is an XML-based file
format that provides a machine-readable description of HTTP-based web
APIs. A WADL file defines the "resources" (that is, URIs) that constitute an
API. For each resource, WADL defines one or more "methods" that act on
those resources. With RESTful APIs, a 'method' is a combination of a
resource (URI) and the HTTP verb (most commonly GET, PUT, POST and
DELETE) that acts on the resource. WADL in its simplest form defines create,
read, update and delete actions (sometimes referred to as CRUD operations)
on resources defined by the API.

10. 06/06/2013Presenter: Łukasz Serwatka Slide 10
APIGEE console & eZ Publish REST
Resources
 An example eZ Publish API that defines 3 resources: objects, locations, and
sections.
 http://api.example.com/api/ezp/v2/content/objects
 http://api.example.com/api/ezp/v2/content/locations
 http://api.example.com/api/ezp/v2/content/sections

11. 06/06/2013Presenter: Łukasz Serwatka Slide 11
APIGEE console & eZ Publish REST
Resources
 Application definition
<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:apigee="http://api.apigee.com/wadl/2010/07/"
xmlns="http://wadl.dev.java.net/2009/02"
xsi:schemaLocation="http://wadl.dev.java.net/2009/02
http://apigee.com/schemas/wadl-schema.xsd
http://api.apigee.com/wadl/2010/07/
http://apigee.com/schemas/apigee-wadl-extensions.xsd">
<!-- Base defines the domain and base path of the endpoint --
>
<resources base="http://api.demo.ez.no/api/ezp/v2">
</resources>
</application>

12. 06/06/2013Presenter: Łukasz Serwatka Slide 12
APIGEE console & eZ Publish REST
Resources
 Resource definition
<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:apigee="http://api.apigee.com/wadl/2010/07/"
xmlns="http://wadl.dev.java.net/2009/02"
xsi:schemaLocation="http://wadl.dev.java.net/2009/02
http://apigee.com/schemas/wadl-schema.xsd
http://api.apigee.com/wadl/2010/07/ http://apigee.com/schemas/apigee-
wadl-extensions.xsd">
<!-- Base defines the domain and base path of the endpoint -->
<resources base="http://api.demo.ez.no/api/ezp/v2">
<!-- A resource with a GET method that requires a template
parameter and a header -->
<resource path="/content/objects/{contentId}">
</resource>
</resources>
</application>

13. 06/06/2013Presenter: Łukasz Serwatka Slide 13
APIGEE console & eZ Publish REST
Resources
 For each resource, developers need a way to create, to read, to update, and
to delete each resource--in other words, a set of methods is required for each
resource.
RESTful APIs usually define a:
 POST method (for creating an article)
 PUT method (for modifying an existing article)
 GET method (for retrieving the article)
 DELETE method (for removing articles)

14. 06/06/2013Presenter: Łukasz Serwatka Slide 14
APIGEE console & eZ Publish REST
Resources
 A single GET method on the /content/objects resource. The method returns a
list of content objects.
<method id="get-content-objects" name="GET"
apigee:displayName="content/objects">
<apigee:tags>
<apigee:tag primary="true">Content Resources</apigee:tag>
</apigee:tags>
<apigee:authentication required="true"/>
<apigee:example url="/content/objects"/>
<doc
apigee:url="http://api.mydomain.com/doc/content/objects">
A GET method that requires a template parameter.
</doc>
</method>

15. 06/06/2013Presenter: Łukasz Serwatka Slide 15
APIGEE console & eZ Publish REST
Resources
 A single method can have a request definition with predefined data
<request>
<representation>
<!-- Set required to true to indicate the content as mandatory in
the Console -->
<apigee:payload required="true">
<!-- Body content. -->
<apigee:content>
<![CDATA[
]]>
</apigee:content>
</apigee:payload>
</representation>
</request>

16. 06/06/2013Presenter: Łukasz Serwatka Slide 16
APIGEE console & eZ Publish REST
Parameters
 Methods can in turn have parameters. Parameters provide additional
granularity over interactions with resources. There are a number of different
ways of working with parameters in WADL.
 One benefit of using the Apigee Console is that it enables developers to
quickly understand which parameters are supported by the API, and how
developers can use parameters to accomplish specific tasks.

17. 06/06/2013Presenter: Łukasz Serwatka Slide 17
APIGEE console & eZ Publish REST
Parameters
 Header parameter example:
<param name="Accept" required="true" type="xsd:string"
style="header"
default="application/vnd.ez.api.Content+json">
<doc>Response format.</doc>
<option value="application/vnd.ez.api.Content+json"
mediaType="application/json"/>
<option value="application/vnd.ez.api.Content+xml"
mediaType="application/xml"/>
</param>

18. 06/06/2013Presenter: Łukasz Serwatka Slide 18
APIGEE console & eZ Publish REST
Parameters
 Template parameter example:
<resource path="/content/objects/{contentId}">
<param name="contentId" required="true" type="xsd:string"
style="template" default="57">
<doc>
eZ Publish Content ID
</doc>
</param>
</resource>

19. 06/06/2013Presenter: Łukasz Serwatka Slide 19
APIGEE console & eZ Publish REST
Parameters
 Query parameter example:
<param name="param1" required="true" type="xsd:string"
style="query" default="12345">
<doc>Parameter description.</doc>
</param>

20. 06/06/2013Presenter: Łukasz Serwatka Slide 20
APIGEE console & eZ Publish REST
Console To-Go