1 Introduction to RESTful Web Services

This chapter provides an overview of developing Java EE web services that conform to the Representational State Transfer (REST) architectural style using Java API for RESTful Web Services (JAX-RS) in WebLogic Server 12.1.3.

This chapter includes the following sections:

For definitions of unfamiliar terms found in this and other books, see the Glossary.

Introduction to the REST Architectural Style

REST describes any simple interface that transmits data over a standardized interface (such as HTTP) without an additional messaging layer, such as Simple Object Access Protocol (SOAP). REST is an architectural style—not a toolkit—that provides a set of design rules for creating stateless services that are viewed as resources, or sources of specific information (data and functionality). Each resource can be identified by its unique Uniform Resource Identifiers (URIs).

A client accesses a resource using the URI and a standardized fixed set of methods, and a representation of the resource is returned. A representation of a resource is typically a document that captures the current or intended state of a resource. The client is said to transfer state with each new resource representation.

Table 1-1 defines a set of constraints defined by the REST architectural style that must be adhered to in order for an application to be considered "RESTful."

Table 1-1 Constraints of the REST Architectural Style

Constraint Description

Addressability

Identifies all resources using a uniform resource identifier (URI). In the English language, URIs would be the equivalent of a noun.

Uniform interface

Enables the access of a resource using a uniform interface, such as HTTP methods (GET, POST, PUT, and DELETE). Applying the English language analogy, these methods would be considered verbs, describing the actions that are applicable to the named resource.

Client-server architecture

Separates clients and servers into interface requirements and data storage requirements. This architecture improves portability of the user interface across multiple platforms and scalability by simplifying server components.

Stateless interaction

Uses a stateless communication protocol, typically Hypertext Transport Protocol (HTTP). All requests must contain all of the information required for a particular request. Session state is stored on the client only.

This interactive style improves:

  • Visibility—Single request provides the full details of the request.

  • Reliability—Eases recovery from partial failures.

  • Scalability—Not having to store state enables the server to free resources quickly.

Cacheable

Enables the caching of client responses. Responses must be identified as cacheable or non-cacheable. Caching eliminates some interactions, improving efficiency, scalability, and perceived performance.

Layered system

Enables client to connect to an intermediary server rather than directly to the end server (without the client's knowledge). Use of intermediary servers improve system scalability by offering load balancing and shared caching.


What are RESTful Web Services?

RESTful web services are services that are built according to REST principles and, as such, are designed to work well on the Web.

RESTful web services conform to the architectural style constraints defined in Table 1-1. Typically, RESTful web services are built on the HTTP protocol and implement operations that map to the common HTTP methods, such as GET, POST, PUT, and DELETE to create, retrieve, update, and delete resources, respectively.

Standards Supported for RESTful Web Service Development on WebLogic Server

The JAX-RS provides support for creating web services according to REST architectural style. JAX-RS uses annotations to simplify the development of RESTful web services. By simply adding annotations to your web service, you can define the resources and the actions that can be performed on those resources. JAX-RS is part of the Java EE 6 full profile, and is integrated with Contexts and Dependency Injection (CDI) for the Java EE Platform (CDI), Enterprise JavaBeans (EJB) technology, and Java Servlet technology.

WebLogic Server supports the following JAX-RS Reference Implementations (RIs):

Each Jersey JAX-RS RI bundle includes the following functionality:

  • Jersey

  • JAX-RS API

  • JSON processing and streaming

For more information about JAX-RS and samples, see Learn More About RESTful Web Services.

Jersey 1.18 (JAX-RS 1.1 RI)

Jersey 1.18 (JAX-RS 1.1 RI) is the default implementation and provides a production quality implementation of the JSR-311 JAX-RS 1.1 specification, defined at: https://jcp.org/en/jsr/summary?id=311.

The following table provides a roadmap of common tasks for developing, packaging and deploying, securing, testing, and monitoring RESTful web services and clients using Jersey 1.18 (JAX-RS 1.1 RI).

Table 1-2 Roadmap for Implementing RESTful Web Services Using Jersey 1.18 (JAX-RS 1.1 RI)

Task More Information

Develop RESTful web services.

Chapter 3, "Developing RESTful Web Services"

Develop clients to invoke the RESTful web service using the Jersey client API.

Developing RESTful Web Service Clients Using Jersey 1.18 (JAX-RS 1.1 RI)

Package and deploy RESTful web services.

Secure RESTful web services.

Chapter 6, "Securing RESTful Web Services and Clients"

Test RESTful web services.

Chapter 7, "Testing RESTful Web Services"

Monitor RESTful web services.

Chapter 8, "Monitoring RESTful Web Services and Clients"

(Optional) Update the version of the Jersey JAX-RS Reference Implementation (RI) used by your RESTful web service applications.

Chapter 13845072, "Updating the Version of Jersey 1.x JAX-RS RI"

(Optional) Upgrade a RESTful web service that was built in the Oracle WebLogic Server 11g Release 1 (10.3.x) environment to run in the Oracle WebLogic Server 12c Release 1 (12.1.x) environment.

"Upgrading a 10.3.x RESTful Web Service (JAX-RS) to 12.1.x" in Upgrading Oracle WebLogic Server


Jersey 2.5.1 (JAX-RS 2.0 RI)

WebLogic Server ships with a pre-built shared library, packaged as a Web application, that is required to run applications that are based on Jersey 2.5.1 (JAX-RS 2.0 RI). To take advantage of Jersey 2.5.1 (JAX-RS 2.0 RI) features, you need to register the shared library, as described in Chapter 2, "Registering Jersey 2.5.1 (JAX-RS 2.0 Reference Implementation)."

Table 1-3 lists key features delivered with Jersey 2.5.1 (JAX-RS 2.0 RI).

Note:

RESTful web services and clients that are built using Jersey 2.5.1 (JAX-RS 2.0 RI) cannot be secured using Oracle Web Services Manager (OWSM) policies. If your applications require the use of OWSM security, then you will need to use the default implementation, Jersey 1.18 (JAX-RS 1.1 RI).

Table 1-3 Key Features in Jersey 2.5.1 (JAX-RS 2.0 RI)

Key Feature Description

Client API

Communicate with RESTful web services in a standard way. The Client API facilitates the consumption of a web service exposed via HTTP protocol and enables developers to concisely and efficiently implement portable client-side solutions that leverage existing and well established client-side HTTP connector implementations.

For complete details, see:

Asynchronous communication

Invoke and process requests asynchronously.

For complete details, see:

Filters and interceptors

Using filters, modify inbound and outbound requests and responses., such as header information. Using interceptors, modify entity input and output streams. Filters and interceptors can be used on both the client and server side.

For complete details, see "Filters and Interceptors" in the Jersey 2.5.1 User Guide.


Table 1-4 provides a roadmap of common tasks for registering and using Jersey 2.5.1 (JAX-RS 2.0 RI) to develop and secure RESTful web services and clients.

Table 1-4 Roadmap for Implementing RESTful Web Services and Clients Using Jersey 2.5.1 (JAX-RS 2.0 RI)

Task More Information

Register the Jersey 2.5.1 (JAX-RS 2.0 RI) shared library.

Chapter 2, "Registering Jersey 2.5.1 (JAX-RS 2.0 Reference Implementation)"

Develop RESTful web services.

Chapter 3, "Developing RESTful Web Services"

Develop clients to invoke the RESTful web services.

Developing RESTful Web Service Clients Using Jersey 2.5.1 (JAX-RS 2.0 RI)

Package and deploy RESTful web services.

Secure RESTful web services.

Test RESTful web services.

Chapter 7, "Testing RESTful Web Services"

Monitor RESTful web services.

Chapter 8, "Monitoring RESTful Web Services and Clients"

(Optional) Migrate existing applications from Jersey 1.x to 2.x.

"Migration Guide" in Jersey 2.5.1 User Guide


Learn More About RESTful Web Services

Table 1-4 provides a list of resources for more information about RESTful web services.

Table 1-5 Resources for More Information

Resource Link

Jersey User Guide

Jersey API Javadoc

Community Wiki for Project Jersey

https://wikis.oracle.com/display/Jersey/Main

JSR-311 JAX-RS

RESTful Web Services (JAX-RS) sample

"Sample Application and Code Examples" in Understanding Oracle WebLogic Server

The Java EE 6 Tutorial—Building RESTful Web Services With JAX-RS

http://docs.oracle.com/javaee/6/tutorial/doc/giepu.html

"Representational State Transfer (REST)" in Architectural Styles and the Design of Network-based Software Architectures (Dissertation by Roy Fielding)

http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm