Chapter 7. Exposing Content through a RESTful API with Web Scripts

There are many ways to interact with the repository programmatically, one of which is via web scripts. Then why devote an entire chapter to the Web Script Framework? Web scripts allow you to define a REST API for the content in the Alfresco repository. REST stands for Representational State Transfer. In a nutshell, REST describes an architectural style of interaction based on simple URL-based requests and responses occurring over HTTP. Rolling your own RESTful API offers a huge advantage in terms of flexibility and implementation speed over other forms of web service, such as SOAP. Web scripts have quickly become the preferred integration method between the frontend and an Alfresco backend, particularly for portals and dynamic websites.

Specifically, in this chapter you will learn how to do the following:

• Write web scripts that create, read, and delete data in the backend repository and return responses in HTML, XML, and JSON...

Introducing the Web Script Framework

Content-centric applications are becoming more and more componentized. This trend is turning traditional content management approaches inside out. Rather than having a single, monolithic system responsible for all aspects of a content-centric web application, loosely coupled subsystems are being integrated to create more agile solutions.

This approach requires that your Content Management System (CMS) has a flexible and lightweight interface. You don't want to be locked in to a presentation approach based on the content repository you are working with. In fact, in some cases, you might have very little control over the tools that will be used to talk to your CMS.

Consider the growing adoption of wikis and blogs within an Enterprise and the increasing popularity of mash-ups both inside and outside the Enterprise. These trends are driving implementations where the CMS is seen as a black-box component with the frontend (or perhaps many different frontends...

Planning the SomeCo whitepapers and ratings API

Before diving into the examples, let's plan the new API at a high level. The following table outlines the URLs, the HTTP methods, and the response formats for each:

URL	Method	Description	Response formats
/someco/whitepapers	GET	Returns a list of whitepapers	HTML, JSON
/someco/rating?id={id}	GET	Gets the average rating for a given whitepaper by passing in the whitepaper's nodeId	HTML, JSON
/someco/rating?id={id}&rating={rating}&user={user}	POST	Creates a new rating for the specified whitepaper by passing in a rating value and the user who posted the rating	HTML, JSON
/someco/rating?id={id}	DELETE	Deletes all ratings for a specified whitepaper	HTML

Tip

The API to create new ratings provides the option of passing the username as argument. From a security point of view, this is not ideal because you could provide any values. The ideal solution would be to retrieve the username from the authentication used...

Retrieving data with web scripts

The first service that needs to be implemented retrieves the list of whitepapers enabled for publication. The web script needs to return the list of whitepapers in two formats: HTML and JSON. HTML will allow you to easily test the service and JSON will make it easy for code on the frontend to process the list. This will require four files: one descriptor, one JavaScript controller, and two FreeMarker templates-one for each format.

Note

New to JSON? It stands for JavaScript Object Notation. It is a way to describe JavaScript objects in plain text. The beauty of it is that it is extremely easy to create and consume, and it isn't as verbose as XML. For more information on JSON, see http://www.json.org.

Step-by-step - writing a web script to list whitepapers

We are going to create all our web scripts in the classpath. By choosing this option, we just package all our extensions in the same module that represent our solution. By just deploying our AMP file, everything...

Writing Java-backed web scripts

You now have a web script that returns all whitepapers, and a web script that returns the rating summary for a specific whitepaper. The next step is to implement a web script that supports the POST method so that people can submit new ratings.

Like all web scripts, the web script that creates ratings will run as the user executing the script. In this case, you are appending guest=true to the URL, but we will use the runAs property in the web script descriptor to run the code using the username admin. Another way to handle this would be to set the web script's minimum authentication level to User, give named users (or one or more groups) write access to the whitepapers folder, and make website users authenticated. But SomeCo doesn't want to set up user accounts for every user who might rate content. Any user ought to be able to rate content whether or not he or she can authenticate with Alfresco as a named user. So, we'll use the runAs option. In this example...

Wiring a web script to UI widgets

SomeCo wants to show a graphical ratings widget on its web page. When the user clicks a star, it should post the corresponding rating to Alfresco. In a subsequent example, you'll see how to leverage the widget on SomeCo's website. For this example, you are going to add the ratings widget to the HTML response for the rating web script. That will let you test both the widget and the rating POST.

Note

We'll use jQuery in our HTML page. For the ratings widget, it is based on code from the library at http://rateyo.fundoocode.ninja/.

You may recall that in the earlier rating example, the HTML response simply showed the rating summary data for a given whitepaper. The goal now is to enhance that response with the rating widget so that the POST can be tested. The following figure shows what the response will look like when you are done. This example whitepaper node has 2 ratings and an average rating of 3:

The purpose of the rating widget is two-fold. First, it graphically...

Handling form data

The rating example makes an AJAX call using the POST method. What if, instead of using AJAX, you were simply posting an HTML form? The web script framework is able to handle form posts, including multi-part forms.

For example, let's implement a new HelloWorld example as a form post instead of passing the name argument in the query string. We can use a static HTML page to render the form, but for the cost of an extra descriptor let's use a web script for both the GET (to render the form) and the POST (to process the form data). To do this, you'll need two descriptors (one for GET and one for POST), two FreeMarker templates, and a JavaScript controller.

Step-by-step - implementing a form-based Hello World

To create a new version of the Hello World web script using a form, do the following:

1. Create a descriptor for the GET called helloworldform.get.desc.xml in repo | src | main | amp | config | alfresco | extension | templates | webscripts | com | someco with the following content...

Advanced web scripts

Now that you have the basics under your belt, let's look at a few advanced web script topics.

Dealing with web script authentication

How web scripts authenticate depends on the runtime you are using. HTTP-based web scripts, such as the ones you built to work with whitepapers and ratings, are configured out of the box to use basic authentication. If you invoke a web script that requires a higher level of authentication than what's already taken place, the browser will present a basic authentication login dialog.

If you have Alfresco configured to leverage an SSO provider such as CAS, web scripts will leverage the session created when the user logs in to the centralized login page. The Chapter 10, Security, contains instructions for installing CAS and integrating it with Alfresco and Alfresco Share.

If you are writing your own web pages that need to invoke authenticated web scripts, one approach is to use a web service call to get a ticket. The ticket is then added to the...

Summary

This chapter gave you an introduction to the Alfresco Web Script Framework. You began with a very simple Hello World script and then gradually moved to more complex examples culminating in a REST API for retrieving whitepapers, getting the average rating for a specific whitepaper, posting new ratings for a given whitepaper, and deleting all ratings for a specific whitepaper.

The SomeCo website was able to leverage the web scripts to add a whitepaper list along with a graphical ratings widget. The widget, the web scripts, and the backend model are generic enough to be used for other types of content as well.

Other takeaways from this chapter include the following:

• Web scripts are mainly composed of an XML descriptor, one or more FreeMarker templates (one for each response format), and, optionally, a controller.

• Controllers can be implemented as JavaScript or Java, and have full access to the Alfresco API. Controllers share data with the view via the model, which is essentially a HashMap...

The rest of the chapter is locked

Retrieving data with web scripts

The first service that needs to be implemented retrieves the list of whitepapers enabled for publication. The web script needs to return the list of whitepapers in two formats: HTML and JSON. HTML will allow you to easily test the service and JSON will make it easy for code on the frontend to process the list. This will require four files: one descriptor, one JavaScript controller, and two FreeMarker templates-one for each format.

Note

New to JSON? It stands for JavaScript Object Notation. It is a way to describe JavaScript objects in plain text. The beauty of it is that it is extremely easy to create and consume, and it isn't as verbose as XML. For more information on JSON, see http://www.json.org.

Step-by-step - writing a web script to list whitepapers

We are going to create all our web scripts in the classpath. By choosing this option, we just package all our extensions in the same module that represent our solution. By just deploying our AMP file, everything...

Writing Java-backed web scripts

You now have a web script that returns all whitepapers, and a web script that returns the rating summary for a specific whitepaper. The next step is to implement a web script that supports the POST method so that people can submit new ratings.

Like all web scripts, the web script that creates ratings will run as the user executing the script. In this case, you are appending guest=true to the URL, but we will use the runAs property in the web script descriptor to run the code using the username admin. Another way to handle this would be to set the web script's minimum authentication level to User, give named users (or one or more groups) write access to the whitepapers folder, and make website users authenticated. But SomeCo doesn't want to set up user accounts for every user who might rate content. Any user ought to be able to rate content whether or not he or she can authenticate with Alfresco as a named user. So, we'll use the runAs option. In this example...

Wiring a web script to UI widgets

SomeCo wants to show a graphical ratings widget on its web page. When the user clicks a star, it should post the corresponding rating to Alfresco. In a subsequent example, you'll see how to leverage the widget on SomeCo's website. For this example, you are going to add the ratings widget to the HTML response for the rating web script. That will let you test both the widget and the rating POST.

Note

We'll use jQuery in our HTML page. For the ratings widget, it is based on code from the library at http://rateyo.fundoocode.ninja/.

You may recall that in the earlier rating example, the HTML response simply showed the rating summary data for a given whitepaper. The goal now is to enhance that response with the rating widget so that the POST can be tested. The following figure shows what the response will look like when you are done. This example whitepaper node has 2 ratings and an average rating of 3:

The purpose of the rating widget is two-fold. First, it graphically...

Handling form data

The rating example makes an AJAX call using the POST method. What if, instead of using AJAX, you were simply posting an HTML form? The web script framework is able to handle form posts, including multi-part forms.

For example, let's implement a new HelloWorld example as a form post instead of passing the name argument in the query string. We can use a static HTML page to render the form, but for the cost of an extra descriptor let's use a web script for both the GET (to render the form) and the POST (to process the form data). To do this, you'll need two descriptors (one for GET and one for POST), two FreeMarker templates, and a JavaScript controller.

Step-by-step - implementing a form-based Hello World

To create a new version of the Hello World web script using a form, do the following:

1. Create a descriptor for the GET called helloworldform.get.desc.xml in repo | src | main | amp | config | alfresco | extension | templates | webscripts | com | someco with the following content...

Advanced web scripts

Now that you have the basics under your belt, let's look at a few advanced web script topics.

Dealing with web script authentication

How web scripts authenticate depends on the runtime you are using. HTTP-based web scripts, such as the ones you built to work with whitepapers and ratings, are configured out of the box to use basic authentication. If you invoke a web script that requires a higher level of authentication than what's already taken place, the browser will present a basic authentication login dialog.

If you have Alfresco configured to leverage an SSO provider such as CAS, web scripts will leverage the session created when the user logs in to the centralized login page. The Chapter 10, Security, contains instructions for installing CAS and integrating it with Alfresco and Alfresco Share.

If you are writing your own web pages that need to invoke authenticated web scripts, one approach is to use a web service call to get a ticket. The ticket is then added to the...

Summary

This chapter gave you an introduction to the Alfresco Web Script Framework. You began with a very simple Hello World script and then gradually moved to more complex examples culminating in a REST API for retrieving whitepapers, getting the average rating for a specific whitepaper, posting new ratings for a given whitepaper, and deleting all ratings for a specific whitepaper.

The SomeCo website was able to leverage the web scripts to add a whitepaper list along with a graphical ratings widget. The widget, the web scripts, and the backend model are generic enough to be used for other types of content as well.

Other takeaways from this chapter include the following:

• Web scripts are mainly composed of an XML descriptor, one or more FreeMarker templates (one for each response format), and, optionally, a controller.

• Controllers can be implemented as JavaScript or Java, and have full access to the Alfresco API. Controllers share data with the view via the model, which is essentially a HashMap...