REST Service Tutorial
Warning: This article describes REST framework before version exo-ws-2.0.
1 Introduction
This HOW-TO explains how to create your own REST based services.
In this HOW-TO we will create a simple calculator, which can do basic operations with integers.
2 Source code
// ...
@URITemplate("/calculator/{item1}/{item2}/")
public class Calculator implements ResourceContainer {
}
Writing
@URITemplate before the class definition gives you the possibility not to set it for each method. Furthermore the class must implement the interface
ResourceContainer. This interface doesn't have any methods, it is just an indication for the
ResourceBinder. Add the code for adding two integers.
// ...
@URITemplate("/calculator/{item1}/{item2}/")
public class Calculator implements ResourceContainer {
@QueryTemplate("operation=add")
@OutputTransformer(StringOutputTransformer.class)
@HTTPMethod("GET")
public Response add(@URIParam("item1") Integer item1,
@URIParam("item2") Integer item2) {
StringBuffer sb = new StringBuffer();
sb.append(item1).append(" + ").append(item2).append(" = ").append(item1 + item2);
return Response.Builder.ok(sb.toString(), "text/plain").build();
}
}
@QueryTemplate("operation=add") - only requests with query parameters "operation=add" can reach this method; @OutputTransformer(StringOutputTransformer.class) - the output transformer; @HTTPMethod("GET") - the HTTP method "GET".
Write the code for other operations in the same way.
Then the result should look like:
package org.exoplatform.services.rest.example;
import org.exoplatform.services.rest.HTTPMethod;
import org.exoplatform.services.rest.OutputTransformer;
import org.exoplatform.services.rest.QueryTemplate;
import org.exoplatform.services.rest.Response;
import org.exoplatform.services.rest.URIParam;
import org.exoplatform.services.rest.URITemplate;
import org.exoplatform.services.rest.container.ResourceContainer;
import org.exoplatform.services.rest.transformer.StringOutputTransformer;
@URITemplate("/calculator/{item1}/{item2}/")
@OutputTransformer(StringOutputTransformer.class)
public class Calculator implements ResourceContainer {
@QueryTemplate("operation=add")
@HTTPMethod("GET")
public Response add(@URIParam("item1") Integer item1, @URIParam("item2") Integer item2) {
StringBuffer sb = new StringBuffer();
sb.append(item1).append(" + ").append(item2).append(" = ").append(item1 + item2);
return Response.Builder.ok(sb.toString(), "text/plain").build();
}
@QueryTemplate("operation=subtract")
@HTTPMethod("GET")
public Response subtract(@URIParam("item1") Integer item1, @URIParam("item2") Integer item2) {
StringBuffer sb = new StringBuffer();
sb.append(item1).append(" - ").append(item2).append(" = ").append(item1 - item2);
return Response.Builder.ok(sb.toString(), "text/plain").build();
}
@QueryTemplate("operation=multiply")
@HTTPMethod("GET")
public Response multiply(@URIParam("item1") Integer item1, @URIParam("item2") Integer item2) {
StringBuffer sb = new StringBuffer();
sb.append(item1).append(" * ").append(item2).append(" = ").append(item1 * item2);
return Response.Builder.ok(sb.toString(), "text/plain").build();
}
@QueryTemplate("operation=divide")
@HTTPMethod("GET")
public Response divide(@URIParam("item1") Integer item1, @URIParam("item2") Integer item2) {
StringBuffer sb = new StringBuffer();
sb.append(item1).append(" / ").append(item2).append(" = ").append(item1 / item2);
return Response.Builder.ok(sb.toString(), "text/plain").build();
}
}
So we are done with the source code.
3 Configuration
Create the directory conf/portal and create the file configuration.xml in it.
Add the following code to this file:
<?xml version="1.0" encoding="ISO-8859-1"?>
<configuration>
<component>
<type>org.exoplatform.services.rest.example.Calculator</type>
</component>
</configuration>4 Build
Now we must create the following directory structure to get the possibility to build the source code using maven.
Then create the file pom.xml using the following:
<project>
<parent>
<groupId>org.exoplatform.ws</groupId>
<artifactId>config</artifactId>
<version>trunk</version>
</parent>
<modelVersionɰ.0.0</modelVersion>
<groupId>org.exoplatform.ws.rest</groupId>
<artifactId>simple.calculator</artifactId>
<packaging>jar</packaging>
<version>trunk</version>
<description>Simple REST service</description>
<dependencies>
<dependency>
<groupId>org.exoplatform.ws.rest</groupId>
<artifactId>exo.rest.core</artifactId>
<version>trunk</version>
</dependency>
</dependencies>
</project>
Build this by executing the command:
andrew@ubu:~/workspace/calculator$ mvn clean install
5 Deploy
We have done all now. Then copy the jar file from the target directory of project exo-tomcat into the server with all prepared stuff for REST services. (You can download it here:
http://forge.objectweb.org/project/download.php?group_id=151&file_id=9862)
So just put the jar file into the
lib directory of the tomcat and restart
it. In the console you should see this message:
[INFO] ResourceBinder - Bind new ResourceContainer: org.exoplatform.services.rest.example.Calculator@19846fd
This message indicates that our service was found, bound and is ready to work.
6 Usage
Open your browser and type the following URL:
http://localhost:8080/rest/calculator/12/5/?operation=add and you should see the next page:
The service is working. This is a very simple example, but it should help developers use the REST framework.
Try to check other URLs.
- http://localhost:8080/rest/calculator/12/5/?operation=subtract - must give "12 - 5 = 7";
- http://localhost:8080/rest/calculator/12/5/?operation=multiply - must give "12 * 5 = 60";
- http://localhost:8080/rest/calculator/12/5/?operation=divide - must give "12 / 5 = 2" (we are working with integers!);
