Chapter 2. Using Automatic REST Mappings

To simplify the creation of RESTful services, FUSE Services Framework can automatically map a Java service to a RESTful interface. The mapping requires that the Java service is defined as a CRUD based class.

Overview

To simplify the creation of RESTful service endpoints, FUSE Services Framework can map the methods of a CRUD (Create, Read, Update, and Destroy) based Java bean class to URIs automatically. The mapping looks for keywords in the method names of the bean, such as get, add, update, or remove, and maps them onto HTTP verbs. It then uses the remainder of the method name to create a URI by pluralizing the field name and appending it to the base URI at which the endpoint is published.

	Note
	For more information about publishing RESTful endpoints, see Chapter 4, Publishing a RESTful Service.

Typical CRUD class

Example 2.1, “Widget Catalog CRUD Class” shows a CRUD based class for updating a catalog of widgets.

Example 2.1. Widget Catalog CRUD Class

import javax.jws.WebService;

@WebService
public interface WidgetCatalog
{
  Collection<Widget> getWidgets();
  Widget getWidget(long id);
  void addWidget(Widget widget);
  void updateWidget(Widget widget);
  void removeWidget(String type, long num);
  void deleteWidget(Widget widget);
}

	Important
	You must use the `@WebService` annotation on any class or interface that you wish to expose as a RESTful endpoint.

The class has six operations that are mapped to a URI/verb pair:

getWidgets() is mapped to a GET at baseURI/widgets.
getWidget() is mapped to a GET at baseURI/widgets/id.
addWidget() is mapped to a POST at baseURI/widgets.
updateWidget() is mapped to a PUT at baseURI/widgets.
removeWidget() is mapped to a DELETE at baseURI/widgets/type/num.
deleteWidget() is mapped to a DELETE at baseURI/widgets.

When FUSE Services Framework sees a method name in the form of getResource(), it maps the method to a GET. The URI is generated by appending the plural form of Resource to the base URI at which the endpoint is published. If Resource is already plural, it is not pluralized. For example, getCustomer() is mapped to a GET on /customers. The method getCustomers() would result in the same mapping.

Any method parameters are appended to the URI. For example, getWidget(long id) is mapped to /widgets/id and getCar(String make, String model) would be mapped to /cars/make/model. A call to getCar(plymouth, roadrunner) would be executed by a GET to /cars/plymouth/roadrunner.

	Important
	FUSE Services Framework only supports get methods that use XML primitives in their parameter list.

Mapping to `POST`

Methods of the form addResource() or createResource() are mapped to POST. The URI is generated by pluralizing Resource. For example createCar(Car car) would be mapped to a POST at /cars.

Mapping to `PUT`

Methods of the form updateResource() are mapped to PUT. The URI is generated by pluralizing Resource and appending any parameters except the resource to be updated. For example updateHitter(long number, long rotation, Hitter hitter) would be mapped to a PUT at /hitters/number/rotation.

	Important
	FUSE Services Framework only supports get methods that use XML primitives in their parameter list.

Mapping to `DELETE`

Methods of the form deleteResource() or removeResource() are mapped to DELETE. The URI is generated by pluralizing Resource and appending any parameters. For example removeCar(String make, long num) would be mapped to a DELETE at /cars/make/num.

	Important
	FUSE Services Framework only supports get methods that use XML primitives in their parameter list.