RESTful Java Web Services - Second Edition

Description

Design scalable and robust RESTful web services with JAX-RS and Jersey extension APIs About This BookGet to grips with the portable Java APIs used for JSON processingDesign solutions to produce, consume, and visualize RESTful web services using WADL, RAML, and SwaggerA step-by-step guide packed with many real-life use-cases to help you build efficient and secure RESTful web APIs in JavaWho This Book Is For If you are a web developer with a basic understanding of the REST concepts but are new to the idea of designing and developing RESTful web services, this is the book for you. As all the code samples for the book are written in Java, proficiency in Java is a must. What You Will LearnIntroduce yourself to the RESTful software architectural style and the REST API design principlesMake use of the JSR 353 APIs and Jackson API for JSON processingBuild portable RESTful web APIs, making use of the JAX-RS 2.0 APISimplify API development using the Jersey extension APIsSecure your RESTful web services with various authentication and authorization mechanismsGet to grips with the various metadata solutions to describe, produce, and consume RESTful web servicesUnderstand the design and coding guidelines to build well-performing RESTful APIsSee how the role of RESTful web services changes with emerging technologies and trendsIn Detail REST (REpresentational State Transfer) is a simple yet powerful software architecture style to create scalable web services and allow them to be simple, lightweight, and fast. The REST API uses HTTP and JSON, so that it can be used with many programming languages such as Ruby, Java, Python, and Scala. Its use in Java seems to be the most popular though, because of the API's reusability. This book is a guide to developing RESTful web services in Java using the popular RESTful framework APIs available today. You will begin with gaining an in-depth knowledge of the RESTful software architectural style and its relevance in modern applications. Further, you will understand the APIs to parse, generate, transform, and query JSON effectively. Then, you will see how to build a simple RESTful service using the popular JAX-RS 2.0 API along with some real-world examples. This book will introduce you to the Jersey framework API, which is used to simplify your web services. You will also see how to secure your services with various authentication mechanisms. You will get to grips with various solutions to describe, produce, consume, and visualize RESTful web services. Finally, you will see how to design your web services to equip them for the future technological advances, be it Cloud or mobile computing. By the end of this book, you will be able to efficiently build robust, scalable, and secure RESTful web services, making use of the JAX-RS and Jersey framework extensions. Style and approach This book is written as a step-by-step guide to designing and developing robust RESTful web services. Each topic is explained in a simple and easy-to-understand manner with lots of real-life use-cases and their solutions. Cover Copyright Credits About the Author Acknowledgments About the Reviewers www.PacktPub.com Table of Contents Preface Chapter 1: Introducing the REST Architectural Style The REST architectural style Introducing HTTP HTTP versions Understanding the HTTP request-response model Uniform resource identifier Understanding the HTTP request methods Representing content types using HTTP header fields HTTP status codes The evolution of RESTful web services The core architectural elements of a RESTful system Resources URI The representation of resources Generic interaction semantics for REST resources The HTTP GET method The HTTP POST method The HTTP PUT method The HTTP DELETE method Hypermedia as the engine of application state Description and discovery of RESTful web services Java tools and frameworks for building RESTful web services Summary Chapter 2: Java APIs for JSON Processing A brief overview of JSON Understanding the JSON data syntax Basic data types available with JSON A sample JSON file representing employee objects Processing JSON data Using JSR 353 – Java API for processing JSON Processing JSON with JSR 353 object model APIs Generating the object model from the JSON representation Generating the JSON representation from the object model Processing JSON with JSR 353 streaming APIs Using streaming APIs to parse JSON data Using streaming APIs to generate JSON Using the Jackson API for processing JSON Processing JSON with Jackson tree model APIs Using Jackson tree model APIs to query and update data Processing JSON with Jackson data binding APIs Simple Jackson data binding with generalized objects Full Jackson data binding with specialized objects Processing JSON with Jackson streaming APIs Using Jackson streaming APIs to parse JSON data Using Jackson streaming APIs to generate JSON Using the Gson API for processing JSON Processing JSON with object model APIs in Gson Generating the object model from the JSON representation Generating the parameterized Java collection from the JSON representation Generating the JSON representation from the object model Processing JSON with Gson streaming APIs Reading JSON data with Gson streaming APIs Writing JSON data with Gson streaming APIs Summary Chapter 3: Introducing the JAX-RS API An overview of JAX-RS JAX-RS annotations Specifying the dependency of the JAX-RS API Using JAX-RS annotations to build RESTful web services Annotations for defining a RESTful resource Annotations for specifying request-response media types Annotations for processing HTTP request methods Annotations for accessing request parameters Returning additional metadata with responses Understanding data binding rules in JAX-RS Mapping the path variable with Java types Mapping the request and response entity body with Java types Using JAXB to manage the mapping of the request and response entity body to Java objects Building your first RESTful web service with JAX-RS Setting up the environment Building a simple RESTful web service application using NetBeans IDE Adding CRUD operations on the REST resource class Client APIs for accessing RESTful web services Specifying a dependency of the JAX-RS client API Calling REST APIs using the JAX-RS client Simplified client APIs for accessing REST APIs Summary Chapter 4: Advanced Features in the JAX-RS API Understanding subresources and subresource locators in JAX-RS Subresources in JAX-RS Subresource locators in JAX-RS Exception handling in JAX-RS Reporting errors using ResponseBuilder Reporting errors using WebApplicationException Reporting errors using application exceptions Mapping exceptions to a response message using ExceptionMapper Introducing validations in JAX-RS applications A brief introduction to Bean Validation Building custom validation constraints What happens when Bean Validation fails in a JAX-RS application? Supporting custom request-response message formats Building a custom entity provider Marshalling Java objects to the CSV representation with MessageBodyWriter Marshalling CSV representation to Java objects with MessageBodyReader Asynchronous RESTful web services Asynchronous RESTful web service client Managing HTTP cache in a RESTful web service Using the Expires header to control the validity of the HTTP cache Using Cache-Control directives to manage the HTTP cache Conditional request processing with the Last-Modified HTTP response header Conditional request processing with the ETag HTTP response header Conditional data update in RESTFul web services Understanding filters and interceptors in JAX-RS Modifying request and response parameters with JAX-RS filters Implementing server-side request message filters Implementing server-side response message filters Implementing client-side request message filters Implementing client-side response message filters Modifying request and response message bodies with JAX-RS interceptors Implementing request message body interceptors Implementing response message body interceptors Managing the order of execution for filters and interceptors Selectively applying filters and interceptors on REST resources by using @NameBinding Dynamically applying filters and interceptors on REST resources using DynamicFeature Understanding the JAX-RS resource lifecycle Summary Chapter 5: Introducing the Jersey Framework Extensions Specifying dependencies for Jersey Programmatically configuring JAX-RS resources during deployment A quick look at the static resource configurations Modifying JAX-RS resources during deployment using ModelProcessor What is Jersey ModelProcessor and how does it work? A brief look at the ModelProcessor interface Building Hypermedia as the Engine of Application State (HATEOAS) APIs Formats for specifying JSON REST API hypermedia links Programmatically building entity body links using JAX-RS APIs Programmatically building header links using JAX-RS APIs Declaratively building links using Jersey annotations Specifying the dependency to use Jersey declarative linking Enable Jersey declarative linking feature for the application Declaratively adding links to resource representation Grouping multiple links using @InjectLinks Declaratively building HTTP link headers using @InjectLinks Reading and writing binary large objects using Jersey APIs Building RESTful web service for storing images Building RESTful web service for reading images Generating chunked output using Jersey APIs Jersey client API for reading chunked input Supporting Server Sent Event in RESTful web services Understanding the Jersey server-side configuration properties Monitoring RESTful web services using Jersey APIs Summary Chapter 6: Securing RESTful Web Services Securing and authenticating web services HTTP basic authentication Building JAX-RS clients with basic authentication Securing JAX-RS services with basic authentication Configuring JAX-RS application for basic authentication HTTP digest authentication Securing RESTful web services with OAuth Understanding the OAuth 1.0 protocol Building the OAuth 1.0 client using Jersey APIs Understanding the OAuth 2.0 protocol Understanding the grant types in OAuth 2.0 Building the OAuth 2.0 client using Jersey APIs Authorizing the RESTful web service accesses via the security APIs Using SecurityContext APIs to control access Using the javax.annotation.security annotations to control access with the Jersey framework Using Jersey's role-based entity data filtering Input validation Summary Chapter 7: The Description and Discovery of RESTful Web Services Introduction to RESTful web services Web Application Description Language An overview of the WADL structure Generating WADL from JAX-RS Generating the Java client from WADL Market adoption of WADL RESTful API Modeling Language An overview of the RAML structure Generating RAML from JAX-RS Generating RAML from JAX-RS via CLI Generating JAX-RS from RAML Generating JAX-RS from RAML via CLI A glance at the market adoption of RAML Swagger A quick overview of Swagger's structure An overview of Swagger APIs Generating Swagger from JAX-RS Specifying dependency to Swagger Configuring the Swagger definition Adding Swagger annotations on a JAX-RS resource class Generating Java client from Swagger A glance at the market adoption of Swagger Revisiting the features offered in WADL, RAML, and Swagger Summary Chapter 8: RESTful API Design Guidelines Identifying resources in a problem domain Transforming operations to HTTP methods Understanding the difference between PUT and POST Naming RESTful web resources Fine-grained and coarse-grained resource APIs Using header parameter for content negotiation Multilingual RESTful web API resources Representing date and time in RESTful web resources Implementing partial response Implementing partial update Returning modified resources to the caller Paging resource collection Implementing search and sort operations Using HATEOAS in response representation Hypertext Application Language RFC 5988 – Web Linking Versioning RESTful web APIs Including the version in resource URI – the URI versioning Including the version in a custom HTTP request header – HTTP header versioning Including the version in a HTTP Accept header – the media type versioning Hybrid approach for versioning APIs Caching RESTful web API results HTTP Cache-Control directive HTTP conditional requests Using HTTP status codes in RESTful web APIs Overriding HTTP methods Documenting RESTful web APIs Asynchronous execution of RESTful web APIs Microservice architecture style for RESTful web applications Using Open Data Protocol with RESTful web APIs A quick look at OData URI convention for OData-based REST APIs Reading resources Querying data Modifying data Relationship operations Summary Appendix: Useful Features and Techniques Tools for building a JAX-RS application Integration testing of JAX-RS resources with Arquillian Adding Arquillian dependencies to the Maven-based project Configuring the container for running tests Adding Arquillian test classes to the project Running Arquillian tests Implementing PATCH support in JAX-RS resources Defining the @PATCH annotation Defining a resource method to handle HTTP PATCH requests Using third-party entity provider frameworks with Jersey Transforming the JPA model in to OData-enabled RESTful web services Packaging and deploying JAX-RS applications Packaging JAX-RS applications with an Application subclass Packaging the JAX-RS applications with web.xml and an Application subclass Configuring web.xml for a servlet 2.x container Configuring web.xml for a Servlet 3.x container Packaging the JAX-RS applications with web.xml and without an Application subclass Configuring web.xml for the servlet 2.x container Configuring web.xml for the servlet 3.x container Summary Index