eZ Community » Blogs » eZ » eZ Publish REST API and Apigee...

By

Łukasz Serwatka

eZ Publish REST API and Apigee Console To-Go

Wednesday 12 June 2013 2:53:30 pm

  • Currently 5 out of 5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

The second eZ UnConference took place in Montpellier, France last week and was a great success. It is always great fun to meet eZ Community members in person and share our experiences. Most of the talks were of course about the new eZ Publish 5 Platform, which should not surprise anyone. Representing the product management team, I gave a talk about how to explore the eZ Publish REST v2 API through a browser using Apigee Console To-Go. The slides from my presentation are available here

 

In this post, I will introduce Apigee Console To-Go and walk through its benefits from an eZ Publish developer point of view. 

 

Let’s get started

Apigee Console To-Go is a browser-based interface with interactive tools and documentation that can be connected to an existing API.  This makes it easy to learn, test, and debug the eZ Publish REST v2 API.  With it, you can find API methods; read their descriptions, requirements, and parameters; interact with them; debug the full requests and responses; and more.

Apigee Console To-Go interprets an API based on a Web Application Description Language (WADL) file.  A WADL file is an XML file that describes a web service API.

We will start by visiting apigee.com and creating a free account. Simply visit  https://accounts.apigee.com/accounts/sign_up and fill in some basic account information.

Next, visit https://apigee.com/ to set up a new console.

 

We have to give our console a name (“eZ Publish”) and provide a URL suffix where our console will be available.

Then, we need to select an authentication mechanism. eZ Publish REST v2 currently supports “Basic HTTP Authentication” only.  We are planning to support OAuth2 soon.

 

In the last setup step we have to upload a WADL file. Let's stop here for a moment to learn more about WADL and how you can create your own API definition file.

 

WADL explained

As mentioned earlier, WADL is an XML-based file format that describes a web service API. 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.

The skeleton for WADL starts with an <application> tag that encapsulates resource definitions.

 
 
<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.example.com/api/ezp/v2">
 
    </resources>
 
</application>
 

The parent <resources> tag supports a “base” attribute, which is the base URL to the eZ Publish API. A base URL consists of an API prefix (“/api”), a provider name (“/ezp”), and a version number (“/v2”).

Within the <resources> tag are individual <resource> tags representing the URIs in our API. The example below shows a template-based resource where parameters are defined in the curly brackets.

 
 
    <!-- Base defines the domain and base path of the endpoint -->
 
    <resources base="http://api.example.com/api/ezp/v2">
 
        <!-- A resource with a GET method that requires a template parameter and a header -->
 
        <resource path="/content/objects/{contentId}">
 
        </resource>
 
    </resources>
 

Each <resource> tag defines the URI in a “path” attribute. Each resource contains one of more methods.

RESTful APIs usually have the following methods:

  • POST (for creating articles)
  • PUT (for modifying articles)
  • GET (for retrieving articles)
  • DELETE (for removing articles)

Let’s define a single GET method on the /content/objects resource that returns a specific object.

 
 
<resource path="/content/objects/{contentId}">
 
    <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>
 
</resource>
 

Each method requires a unique identifier, which is very important for Apigee. Note also the tags feature, which can be used to group API methods. For example, it is possible to group all GET-based methods or methods that are responsible for creating content.

Next, let's define a POST method for creating an object. POST and PUT methods can have a request definition with predefined data. Supposing that we want to create a new folder by default when a POST request is sent to the server, the basic structure for this method is as follows:

 
 
<method id="post-content-objects" name="POST" apigee:displayName="content/objects">
 
    <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>
 
</method>
 

Within the CDATA tag you would put the default input data. The eZ Publish REST API supports JSON and XML formats. Here is a JSON example that creates a new folder.

 

{

    "ContentCreate": {

        "ContentType": {

            "_href": "/content/types/1"

        },

        "mainLanguageCode": "eng-GB",

        "User": {

            "_href": "/user/users/14"

        },

        "LocationCreate": {

            "ParentLocation": {

                "_href": "/content/locations/1/2"

            },

            "priority": "0",

            "hidden": "false",

            "sortField": "PATH",

            "sortOrder": "ASC"

        },

        "Section": {

            "_href": "/content/sections/1"

        },

        "alwaysAvailable": "true",

        "remoteId": "remoteId12345678",

        "modificationDate": "2012-10-18T11:00:00",

        "fields": {

            "field": [

                {

                    "fieldDefinitionIdentifier": "name",

                    "languageCode": "eng-GB",

                    "fieldValue": "New Folder"

                },

                {

                    "fieldDefinitionIdentifier": "short_description",

                    "languageCode": "eng-GB",

                    "fieldValue": {

                        "xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><section xmlns:image=\"http://ez.no/namespaces/ezpublish3/image/\" xmlns:xhtml=\"http://ez.no/namespaces/ezpublish3/xhtml/\" xmlns:custom=\"http://ez.no/namespaces/ezpublish3/custom/\"><section><paragraph>This is short description</paragraph></section></section>"

                    }

                }

            ]

        }

    }

}               
 

Methods can have parameters to provide additional granularity over interactions with resources. There are a number of different ways of working with parameters in WADL. One of the benefits 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 the parameters to accomplish specific tasks.

We can have three different types of parameters: Query, Header, and Template.

The Query type is specified by appending GET parameters to the resource URI (“?param1=value&param2=value” for example):

 
 
<param name="param1" required="true" type="xsd:string" style="query" default="12345">
 
    <doc>Parameter description.</doc>
 
</param>
 

The Header type is specified by sending a request header.

 
 
<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>
 

As for the Template type, you have probably noticed that our example resource has a path “/content/objects/{contentId}” where “{contentId}” is a template “variable”. (It is automatically replaced by the Apigee console when you type a value in the relevant field.)

 
 
 
<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>
 

That's it! Once you've uploaded a valid WADL file, you should have a working Apigee API Console.

 

 

The example WADL file used in this tutorial can be downloaded here.

 Once you have a working console, you can further customize it by editing its look and feel. You can also embed the console onto any webpage via an iframe.

 

 In the upcoming weeks we will be working on defining the full eZ Publish REST v2 API in a WADL file and we will release a dedicated console for testing purposes. Stay tuned!

Proudly Developed with from