This tutorial shows how to build a simple Representational State Transfer (REST) API server by using the Java API for RESTful web services (JAX-RS).
Time to Complete
Approximately 1 hour
REST is an architectural style for stateless client/server communications. Web services that use this architectural style, also called RESTful web services or applications, access services which are identified by URLs. These services are acted upon by a set of methods that describe actions which will be performed on them. REST often relies on HTTP to describe such actions.
JAX-RS simplifies the development of RESTful web services by using Java. JAX-RS uses annotations to map Hyptertext Transfer Protocol (HTTP) methods into Java objects. JAX-RS is part of the Java Platform, Enterprise Edition 6 (Java EE 6).
In this tutorial you first learn the basics of RESTful web services and how you can use JAX-RS to build such applications. Later on, you develop a REST API server by using JAX-RS that is capable of responding to the four basic HTTP methods: POST, GET, PUT, and DELETE. Finally, you deploy the REST server and test it by using RESTClient, an application for testing HTTP communications.
The following is a list of software requirements needed to accomplish this tutorial:
- Download and install Java EE 6 SDK from http://www.oracle.com/technetwork/java/javaee/downloads/index.html
- Download and install NetBeans 7.2 from http://www.netbeans.org/downloads/index.html
- Download and install Oracle WebLogic Server Zip Distribution from http://www.oracle.com/technetwork/middleware/weblogic/downloads/index.html
- This tutorial uses NetBeans IDE 7.2 and WebLogic 12.1.1 as the web server but you may use any other Java EE web profile compliant server. For more information on such servers, refer to http://www.oracle.com/technetwork/java/javaee/overview/compatibility-jsp-136984.html
- To install and configure WebLogic Server 12c in NetBeans, refer to: Installing, Configuring, and Testing WebLogic Server 12c Developer Zip Distribution in NetBeans
- Download and install RESTClient 3.1 GUI from http://code.google.com/p/rest-client/downloads/list
Before starting this tutorial, you should:
- Have knowledge of the Java 7 Programming Language.
- Have basic knowledge of the Java EE 6 Platform, specifically Servlets and JSP.
- Have basic knowledge of REST architecture, RESTful web services, and HTTP methods.
RESTful Web Services and JAX-RS Overview
This section gives a brief introduction to RESTful web services and JAX-RS.
What Are RESTful Web Services?
RESTful web services are applications that work based on the Representational State Transfer (REST) architectural style. In this style, data and functionality are considered resources and accessed by using Uniform Resource Identifier (URIs). These resources are acted upon by using a set of simple, well-defined operations.
RESTful web services use HTTP protocol methods to operate on resources. These methods are typically mapped to create, read, update, and delete operations. The following table shows the HTTP methods and the actions they typically perform.
|HTTP Method||Action Performed|
|POST||Creates a resource|
|GET||Reads a resource|
|PUT||Updates a resource|
|DELETE||Deletes a resource|
What Is JAX-RS?
Java API for RESTful Web Services (JAX-RS, defined in JSR-311) is a specification designed for creating RESTful web services in the Java platform. JAX-RS provides Java programming language annotations to map Plain Old Java Objects (POJO) as web resources.
The following table shows the annotations that are used in this tutorial:
|@POST||Corresponds to the HTTP POST method. The Java method annotated with this request method designator processes HTTP POST requests.|
|@GET||Corresponds to the HTTP GET method. The Java method annotated with this request method designator processes HTTP GET requests.|
|@PUT||Corresponds to the HTTP PUT method. The Java method annotated with this request method designator processes HTTP PUT requests.|
|@DELETE||Corresponds to the HTTP DELETE method. The Java method annotated with this request method designator processes HTTP DELETE requests.|
|@Path||Specifies the relative URI path where the application is hosted|
|@Produces||Specifies the MIME media types of representations that a resource can consume|
Note: To see a complete list of JAX-RS annotations, see the JAX-RS APIs at: http://docs.oracle.com/javaee/6/api/
Creating a Java EE 6 Web Project
In this section, you create a new Java EE 6 web application on which you’ll build the REST API server on.
Creating a RESTful Web Service Template
In this section you will create a RESTful web service by using NetBeans.
The RestServer.java resource is added to the project. This file provides a template for creating a RESTful web service.
Creating the Messages Backing Bean
In this section, you create a JavaBeans for storing, manipulating, and exposing messages.
Creating an Interface to Define the Message Methods and Manipulate Them
Creating the Message Service Implementation
The service message implementation is created.
Creating the Messages REST Server by Using JAX-RS
In this section, you will model and build the REST serverby using JAX-RS annotations.
Define the actions that the API will perform. In this case, the Messages REST Server will handle the actions shown in the following table:
||Retrieves all messages|
||Retrieves message with the specified ID|
|/messages||POST||Plain text string||Creates a new message.|
|/messages/<id>||PUT||Plain text String||Updates message with the specified ID|
||Deletes message with the specified ID|
Testing the REST Server
In this section, you test the REST server that you just built by using RESTClient. RESTClient is an application that sends HTTP requests to a specified server.
Creating a New Message by Using the POST HTTP Method
Retrieving Messages by Using the GET HTTP Method
Retrieving a Specific Message by Using the GET HTTP Method
Updating Messages by Using the PUT HTTP Method
Deleting Messages by Using the DELETE HTTP Method
In this tutorial you learned about the basics of RESTful web services in the Java EE 6 platform. Afterwards, you learned about JAX-RS, the Java API for RESTful web services and how it maps HTTP methods to create. read, update, delete operations by using annotations.
You also learned how to:
- Create a Java RESTful web service project
- Model and build a simple REST API server by using JAX-RS capable of responding to the four basic HTTP methods: POST, GET, PUT, and DELETE
- Deploy and test the REST API server
For more information on the topics in this tutorial:
- The Java EE 6 Tutorial
- Oracle blog on Adding RESTful web services to Oracle Identity Manager 11g
- RESTful Web Services
- The Java API for RESTful Web Services (JAX-RS) -- Rapidly Build Lightweight Web Services
- Oracle courses and learning paths for Java EE 6.
- To learn more about Java EE 6, refer to additional OBEs in the Oracle Learning Library.
- Lead Curriculum Developer: Miguel Salazar
- Other Contributors: Eduardo Moranchel
To help navigate this Oracle by Example, note the following:
- Hiding Header Buttons:
- Click the Title to hide the buttons in the header. To show the buttons again, simply click the Title again.
- Topic List Button:
- A list of all the topics. Click one of the topics to navigate to that section.
- Expand/Collapse All Topics:
- To show/hide all the detail for all the sections. By default, all topics are collapsed
- Show/Hide All Images:
- To show/hide all the screenshots. By default, all images are displayed.
- To print the content. The content currently displayed or hidden will be printed.
To navigate to a particular section in this tutorial, select the topic from the list.