eXo Platform - WS - Create a REST service HOW-TO

The create REST service step by step HOW-TO.

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.

1. 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, and the class must implement the interface ResourceContainer. This interface doesn't have any methods, it is just a mark for ResourceBinder. Then 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 must 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.

2. Configuration.

Create the directory conf/portal and create the file configuration.xml in it. Add the following code into this file:

<?xml version="1.0" encoding="ISO-8859-1"?>
<configuration>
  <component>
    <type>org.exoplatform.services.rest.example.Calculator</type>
  </component>
</configuration>

3. Build.

Now we must create the following directory structure to get the possibility to build 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&#624;.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

4. 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 console you must see the next string:

[INFO] ResourceBinder - Bind new ResourceContainer: org.exoplatform.services.rest.example.Calculator@19846fd

this indicates that our service was found, bound and is ready to work.

5. Usage.

Open your browser and type the following URL: http://localhost:8080/rest/calculator/12/5/?operation=add and you must see the next page:

The service is working. This is a very simple example, but it must 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!);

last modified by Nicolas Filotto on 22/08/2008 at 01:31

Create REST service step by step HOW-TO

Top Menu

The create REST service step by step HOW-TO.

1. Source code.

2. Configuration.

3. Build.

4. Deploy.

5. Usage.

Search

Products

eXo Optional Modules

eXo Core Fundations

Recently Modified