eZ Community » Blogs » Piotr Nalepa » How to build great web/mobile...

By

How to build great web/mobile applications using eZ JS REST Client?

Wednesday 03 December 2014 1:47:13 pm

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

Nowadays, creating web applications without reliable access to data sources is impossible. Frequently, one of the main data sources are services based on REST architecture.

What is REST?

REST is an abstraction of the architecture of the World Wide Web. By Wikipedia, "REST is an architectural style consisting of a coordinated set of architectural constraints applied to components, connectors, and data elements, within a distributed hypermedia system. REST ignores the details of component implementation and protocol syntax in order to focus on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements."

Essentially, REST is an architecture style for designing networked applications. The applications are using HTTP requests to communicate with servers, to post data (create or update), read data and delete data.

REST in eZ Publish

The eZ Publish platform is able to serve data using REST architecture. Developers can use it with PHP and JS REST Clients, which are provided by eZ. In this article you will find some interesting examples for how to use JS REST Client to build web and mobile applications based on eZ Publish. There are few points you have to know before starting to use eZ JS REST Client:

  1. It's based on eZ Publish, of course,
  2. You can do CRUD (create, read, update, delete) operations using it,
  3. It follows HATEOAS (Hypermedia as the Engine of Application State) principle.

The REST API should be discoverable. Every response should include links to further resources instead of ids to resources. The main advantage of using REST API provided by eZ Publish is a possibility to create very good web/mobile applications based on reliable REST service, that allows for the ability to not only fetch content data from eZ Publish, but allows creating, updating and deleting content data, as well. It's better than every other service which allows only to download pieces of data about content and don't allow to modify them in any way.

What is eZ JS REST Client?

It's a piece of software created in a framework-agnostic way (without any help of frameworks like YUI3, Angular.js or Backbone.js). That means you can use it with every JS framework library of your preference. One of its dependencies is a library Q.js, which is responsible for handling asynchronous events, that's why developers are able to work on the data they are expecting, as they are loaded, no earlier. The extraordinary thing in the REST API provided by eZ Publish is that you can create great web/mobile applications, which functionalities don’t end on fetching data from the service, allowing you to create new content, as well, and then save it using REST API.

How to start working with eZ JS REST Client?

The first thing you have to do is to download the client using either bower dependency management system or just download it from the eZ JS REST Client repository on Github. If you choose bower, you should run the command:

 bower install --save ezsystems/ez-js-rest-client

Then you should include the client's JS file - CAPI-min.js - just before the closing tag of BODY in your HTML file or include it using AMD pattern, you choose which one suits you the most. Finally in you application you can start using it by doing that:

var pageUrl = 'http://ez.local',         authAgent = new SessionAuthAgent({                 login: "admin",                 password: "admin"         }),         jsRestClient = new CAPI(pageUrl, authAgent);

The pageUrl param contains a path to the website, that provides the REST service endpoints; the authAgent is a session authentication object required to connect with REST service.

Usage examples

As I mentioned earlier you can do multiple things using that client, like creating new content, fetching content data, or even removing content from the service, it's up to you. I'm going to give you some examples of what you can do and how you can do it.

Fetch a list of content types
var contentTypeService = jsRestClient.getContentTypeService(),         callback = function (error, response) { ... }// load content type groups data 
contentTypeService.loadContentTypeGroups(callback)// That action should be performed  // inside the callback of `loadContentTypeGroups` method,  // when loading content type groups. // For each content type group, load content type data 
contentTypeService.loadContentTypes(group._href, callback);

To fetch a list of content types you have to use the Content Type Service provided with eZ JS REST Client. REST API always performs actions in the provided callback, it uses 2 parameters - the error  param has boolean value (true or false) and the response is an object which contains information returned from the service as a JSON object.

Create new content
var contentService = jsRestClient.getContentService(),           struct = contentService.newContentCreateStruct({ ... });  
 
contentService.createContent(struct, callback);

To create new content you have to use the Content Service provided with eZ JS REST Client. Then you have to create a new content structure by providing an information object as a param of newContentCreateStruct method. Finally, you call createContent method with 2 parameters - the struct and the callback (the same as in the previous example).

Get a list of drafts created by a user
var contentService = jsRestClient.getContentService(),         userId = 21,          draftsUrl = userId + '/drafts';  
contentService.loadContent(draftsUrl, '', '', '', callback);

In the example above, you have to also use the Content Service. For simplicity, the userId variable is set to 21. The eZ JS REST Client doesn't have any endpoint to get information about drafts created by a user, so we have to prepare the endpoint ourselves, just like it's done above in the draftsUrl variable. Finally, you can send a request using loadContent method. The 3 params between draftsUrl and callback params are not required and they are set to empty strings.

Summing Up

On the basis of the examples above, now you can see how to use eZ Publish REST API for your purposes. You can create content, fetch data about content and you can edit it. You can do almost everything you want to make your app great. Regarding the eZ JS REST Client, there are planned improvements on performance, new functionalities and new endpoints (eq. for drafts).

Proudly Developed with from