RESTful Web Services in TYPO3 CMS

Introduction

Every system uses resources. These resources can be pictures, business information or anything else that can be represented in a system. The meaning of web services is to give the client an option to access these resources in an easy way. Representational State Transfer (REST) has gained widespread acceptance across the Web as a simpler alternative to SOAP- and Web Services Description Language (WSDL)-based Web services. REST interfaces using resources identified by Uniform Resource Identifier (URI).

In order to use RESTful Web Services in Typo3 CMS we developed an extension/framework which makes it easy to implement Web Services in other extensions. We have oriented ourselves in the development of the extension to the Java Framework Jersey.

Installation

To install the extension, perform the following steps:

1. Go to the Extension Manager
2. Install the extension realurl, if not already done so
3. Install the extension bdegmbh_webservices

Configuration

In the standard configuration, the extension expects that all web services are under the path /services. If the path /services is already being used in your installation, you must change the path in the extension configuration.

How to use

The extension works with annotations and analyzes them to determine the path and the required parameters for the method call.  This section shows how to use annotations to create RESTful web services. The following code example is a very simple example of a root resource class using annotations.

/**
 * @Path /show
 */
class ShowHelloWorld
{
    /**
     * @GET
     * @Path /helloworld
     */
    public function getHello() {
       return "Hello world";
    }
}

Let's look at some of the annotations used in this example. In the following we assume that serviceRoot is set to services.

@Path

The annotation value is a relative URI path. It must be used as class and method annotation. In the example above, the PHP class will be hosted at the URI path /services/show/helloworld. This is an extremely simple use of the @Path annotation.

URI path templates are URIs with variables embedded within the URI syntax. These variables are substituted at runtime in order for a resource to respond to a request based on the substituted URI. Variables are denoted by curly braces. For example, look at the following @Path annotation:

@Path /add/{username}

In this example, the web service is used to create a new user in our application. For a new user like "steve" the URL is the following: example.com/services/users/add/steve

The corresponding PHP class looks like this:

/**
 * @Path /users
 */
class UserService
{
    /**
     * @GET
     * @Path /add/{username}
     */
    public function addUser($username) {
       ...
    }
}

The framework analyzes the template and passes the values from the URL in the corresponding method parameters. The names of the method parameters and the name of the template must match. If it is required, it is possible to declare a particular regular expression, which overrides the default regular expression, "[^/]+", for example:

@Path /add/{username: [a-zA-Z][a-zA-Z_0-9]*}

In this example the username variable will only match user names that begin with one upper or lower case letter and zero or more alpha numeric characters and the underscore character.

A @Path value must begin with a '/'.

@GET, @POST (HTTP Methods)

@GET and @POST are resource method designator annotations which correspond to the similarly named HTTP methods. In the example above, the method will process HTTP GET requests. The behavior of a resource is determined by which of the HTTP methods the resource is responding to.

@Produces

The @Produces annotation is used to specify the MIME media types of representations a resource can produce and send back to the client. @Produces can be applied at both the class and method levels. If no @Produces annotation was found, the default media type is text/html.

If required, more than one media type can be declared in the same @Produces declaration, for example:

@Produces application/xml, application/json

Which of the media types is used, depends on the request of the client.

@QueryParam

@QueryParam is used to extract query parameters from the Query component of the request URL or it extracts information from a request representation that is of the MIME media type "application/x-www-form-urlencoded". It depends on the HTTP method which is used (GET or POST).

Suppose the user name, first name and surname are passed through a form, the program looks like this.

Namespace Example\Services;

/**
 * @Path /users
 */
class UserService
{
    /**
     * @POST
     * @Path /add
     * @QueryParam username
     * @QueryParam firstname
     * @QueryParam surname
     */
    public function addUser($username, $firstname, $surname) {
       ....
    }
}

Activate the web service

The final step is to activate your web service in the extension’s ext_tables.php file.

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['bdegmbh_webservices']['services'][]= 
  'EXT:'.$_EXTKEY.'/Classes/Services/UserService.php:Example\Services\UserService';

That's all. If you have any questions or suggestions, do not hesitate to contact us.