Motivation

Web services are a standard way to achieve interoperability between systems. There are two approaches for developing Web Services: SOAP (Simple Object Access Protocol) and the REST (Representational State Transfer) architectural style.

REST has gained widespread acceptance across the Web as a simpler alternative to SOAP and WSDL based Web Services. Key evidence of this shift is the adoption of REST by mainstream Web 2.0 service providers, including Yahoo, Google and Facebook, in favor of an easier-to-use, resource-oriented model to expose their services.

Mule supports the development of SOAP Web Services via the CXF module but it lacks the support to create and expose RESTful services/resources.

There are two primary elements of REST support that Mule should provide:

1. The ability to easily expose REST resources
2. The ability to easily consume external REST resources.

The latter can currently be done using outbound dynamic http endpoints but we have limited support for the former. The current recommended approach is to use a Jersey component that defines what is exposed via REST on a method by method basis inside the component implementation. While useful this is not what user expect from Mule, users expect to be able to easily implement different operations on resources using message processors or flow.

Design

The goal is to provide users with a simple way to expose their resources or RESTful services via a Mule configuration pattern.

The chosen approach facilitates a resource-oriented approach to creation of REST services. Where each resources has a unique path under the base uri.

The XML configuration approach is the following:

Rest-resources will be a patten (same level as flow). It will support http/https transports only.

This pattern will be added to the http transport module. Either with the http namespace or a rest namespace.

The rest-resources element contains the baseUri of the resources and a list of resources. Each rest-resource has a path to the resource that can contain variable placeholders using curly braces.
If the incoming URI matches the path of a resource it will extract the variables and make them available as properties.

The HTTP methods GET, POST, PUT and DELETE map to the operations that need to be carried out on the resource. If a request it received for an undefined method than a "405 Method Not Allowed" status code will be returned.

Default behavior

The pattern will implement default behavior in case everything worked as expected or an error occurred, for instance:

• Return HTTP Status 200, if no error occurred.

• Return HTTP Status 404, if in a 'GET' request the resource was not found (resource URI does not match any resource).

• Return HTTP Status 500, if an Exception was raised processing the request in any of the HTTP methods.

• Return HTTP Status 403, if a Security Exception is raised processing the request in any of the HTTP methods.

• Return HTTP Status 405, if an undefined method is requested.

Note: In case of a resource not found exception when I'm doing a GET request, there is no way to differentiate between a not found exception and a any other processing exception, so the pattern will return a 500 Status. The user can override the default behavior if he wants to return something else.

Ability to configure exception strategies

The user should be able to handle the exceptions raised within the pattern and override the default behavior. This can be done using the Mule Exception Strategies. For that it's necessary to be able to reference a global exception strategy at three different levels:

1. At the pattern level: This way the user can declare an exception strategy to be invoked if an exception is raised within the pattern.
2. At the resource level: This way the user can declare an exception strategy to be invoked if an exception is raised for this particular path. The exception strategy declared here will override the exception strategy that might have been declared at the pattern level.
3. At the HTTP method level: This way the user can declare an exception strategy to be invoked if an exception is raised for this particular method in this specific resource. The exception strategy declared here will override any exception strategy declared at higher levels.

Ability to easily create HTTP responses

The pattern should provide an easy way to create HTTP responses. For that end an http:response element can be created which would let the user define:

• The status code, using an Enum to make it simpler for users not aware of the HTTP status code numbers.
• The content type
• The headers, such as the location header
• The response body

Still working on the definition of this element.

Example Use Case

Expose resources from the Mule's Object Store as RESTful services.

The following is an example where a Client resource has a list of Orders. The example uses the Object Store Module to manipulate object stores within Mule. It does not cover the handle of exceptions, the three methods of the object store will throw an Exception if there was any problem performing the operations.

Studio impact

As of today, Studio does not support patterns. Once it does, it would be good to add a Wizard to help create the REST configuration.