Get started with IBM JAX-RS

JAX-RS is a collection of interfaces and Java annotations that simplifies development of server-side REST applications. By using JAX-RS technology, Representational State Transfer (REST) applications are easier to develop and easier to consume when compared to other types of distributed systems.

JAX-RS is a Java API for developing REST applications quickly. While JAX-RS provides a faster way of developing web applications than servlets, the primary goal of JAX-RS is to build RESTful services. JAX-RS 1.0 defines a server-side component API to build REST applications. The IBM implementation of JAX-RS provides an implementation of the JAX-RS (JSR 311) specification.

Use this Getting Started guide to help quickly develop and deploy a simple JAX-RS web application.

This procedure illustrates developing a simple Hello World service that is packaged inside a web application archive (WAR) module.

Tasks

1. Create a Java class. This class is used to represent a type of resource.

   package com.ibm.jaxrs.sample;
   
   public class HelloWorldResource {
   
   }
   

2. Annotate the Java class with a javax.ws.rs.Path annotation. The value of the annotation is the relative part of the URL after the application context. The application context is fully defined during deployment. In JAX-RS terminology, this class is known as a root resource.

   package com.ibm.jaxrs.sample;
   
   @javax.ws.rs.Path("/helloworld")
   public class HelloWorldResource {
   
   }
   

3. Create a Java method that returns a Hello World! response. It is intended for the method to be invoked when an HTTP request is received.

   package com.ibm.jaxrs.sample;
   
   @javax.ws.rs.Path("/helloworld")
   public class HelloWorldResource {
   
       public String sayHelloWorld() {
           return "Hello World!";
       }
   }
   

4. Add a javax.ws.rs.GET annotation to the Java method.

   Now, whenever an HTTP GET request is received by the application to the /helloworld path, the sayHelloWorld Java method is invoked. The response message body will contain Hello World! as its content.

   package com.ibm.jaxrs.sample;
   
   @javax.ws.rs.Path("/helloworld")
   public class HelloWorldResource {
   
       @javax.ws.rs.GET
       public String sayHelloWorld() {
           return "Hello World!";
       }
   }
   

   The resource implementation is now complete.

5. We must create the JAX-RS javax.ws.rs.core.Application configuration subclass. This subclass needs to return the set of Java classes that is relevant to the JAX-RS runtime environment.

   package com.ibm.jaxrs.sample;
   
   public class HelloWorldAppConfig extends javax.ws.rs.core.Application {
       public Set<Class<?>> getClasses() {
           Set<Class<?>> classes = new HashSet<Class<?>>();
           classes.add(com.ibm.jaxrs.sample.HelloWorldResource.class);
           return classes;
       }
   }
   

6. Create the web.xml web module configuration file.

   The file tells the web container that the web module contains the IBM JAX-RS REST servlet. We must initialize the IBM JAX-RS Rest servlet with the application configuration class.

   <?xml version="1.0" encoding="UTF-8"?>
   <web-app id="WebApp_9" version="2.4" xmlns=http://java.sun.com/xml/ns/j2ee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"> 
       <servlet>
           <servlet-name>HelloWorldApp</servlet-name>
           <servlet-class>com.ibm.websphere.jaxrs.server.IBMRestServlet</servlet-class>
           <init-param>
               <param-name>javax.ws.rs.Application</param-name>
               <param-value>com.ibm.jaxrs.sample.HelloWorldAppConfig</param-value>
           </init-param>
           <load-on-startup>1</load-on-startup>
       </servlet>
       <servlet-mapping>
           <servlet-name>HelloWorldApp</servlet-name>
           <url-pattern>/rest/*</url-pattern>
       </servlet-mapping>
   </web-app>
   

   See the servlet mapping specified in the previous example. The pattern is used to help determine the final URL of the RESTful service.

7. Add the j2ee.jar file to the classpath.

   Get the j2ee.jar file from the app_server_root/dev/JavaEE directory and add the JAR file to the classpath. Compile the classes.

8. Assemble the web application.

   By using the jar command-line tool that is included with the JDK, run the following command:

   jar cvf helloworld-jaxrs.war *
   

   This command creates a WAR file.
9. Deploy the application onto the application server.

   When deploying the application, we might be prompted to provide a value for the context root of the module. The context root is used to define the application context.

   When using the IBM JAX-RS servlet, the following URL defines the application context:

   http://<your_hostname>:<your Web_container_port>/<context_root_of_Web_application>/servlet_mapping_pattern
   

   Root resource URLs specified by the @javax.ws.rs.Path values are relative to the application context root. Therefore, if the context root is defined as myapplication during deployment, the URL pattern is defined in the web.xml file as /rest/*, and the Java root resource class has a @javax.ws.rs.Path value of /helloworld. An example of the final URL is:

   http://localhost:9080/myapplication/rest/helloworld
   

   Now, we can send a client request to the final URL using a web browser or any other HTTP client.

We have developed and deployed a JAX-RS web application on the application server.

Related:

Overview of IBM JAX-RS

Planning to use JAX-RS to enable RESTful services

Implement JAX-RS web applications

Directory conventions