You are previewing RESTful Java Web Services - Second Edition.
O'Reilly logo
RESTful Java Web Services - Second Edition

Book Description

Design scalable and robust RESTful web services with JAX-RS and Jersey extension APIs

About This Book

  • Get to grips with the portable Java APIs used for JSON processing

  • Design solutions to produce, consume, and visualize RESTful web services using WADL, RAML, and Swagger

  • A step-by-step guide packed with many real-life use-cases to help you build efficient and secure RESTful web APIs in Java

  • Who 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 Learn

  • Introduce yourself to the RESTful software architectural style and the REST API design principles

  • Make use of the JSR 353 APIs and Jackson API for JSON processing

  • Build portable RESTful web APIs, making use of the JAX-RS 2.0 API

  • Simplify API development using the Jersey extension APIs

  • Secure your RESTful web services with various authentication and authorization mechanisms

  • Get to grips with the various metadata solutions to describe, produce, and consume RESTful web services

  • Understand the design and coding guidelines to build well-performing RESTful APIs

  • See how the role of RESTful web services changes with emerging technologies and trends

  • In 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.

    Downloading the example code for this book You can download the example code files for all Packt books you have purchased from your account at http://www.PacktPub.com. If you purchased this book elsewhere, you can visit http://www.PacktPub.com/support and register to have the files e-mailed directly to you.

    Table of Contents

    1. RESTful Java Web Services Second Edition
      1. Table of Contents
      2. RESTful Java Web Services Second Edition
      3. Credits
      4. About the Author
      5. Acknowledgments
      6. About the Reviewers
      7. www.PacktPub.com
        1. Support files, eBooks, discount offers, and more
          1. Why subscribe?
          2. Free access for Packt account holders
      8. Preface
        1. What this book covers
        2. What you need for this book
        3. Who this book is for
        4. Conventions
        5. Reader feedback
        6. Customer support
          1. Downloading the example code
          2. Errata
          3. Piracy
          4. Questions
      9. 1. Introducing the REST Architectural Style
        1. The REST architectural style
        2. Introducing HTTP
          1. HTTP versions
          2. Understanding the HTTP request-response model
          3. Uniform resource identifier
          4. Understanding the HTTP request methods
          5. Representing content types using HTTP header fields
          6. HTTP status codes
          7. The evolution of RESTful web services
        3. The core architectural elements of a RESTful system
          1. Resources
          2. URI
          3. The representation of resources
          4. Generic interaction semantics for REST resources
            1. The HTTP GET method
            2. The HTTP POST method
            3. The HTTP PUT method
            4. The HTTP DELETE method
          5. Hypermedia as the Engine of Application State
        4. Description and discovery of RESTful web services
        5. Java tools and frameworks for building RESTful web services
        6. Summary
      10. 2. Java APIs for JSON Processing
        1. A brief overview of JSON
          1. Understanding the JSON data syntax
          2. Basic data types available with JSON
          3. A sample JSON file representing employee objects
        2. Processing JSON data
        3. Using JSR 353 – Java API for processing JSON
          1. Processing JSON with JSR 353 object model APIs
            1. Generating the object model from the JSON representation
            2. Generating the JSON representation from the object model
          2. Processing JSON with JSR 353 streaming APIs
            1. Using streaming APIs to parse JSON data
            2. Using streaming APIs to generate JSON
        4. Using the Jackson API for processing JSON
          1. Processing JSON with Jackson tree model APIs
            1. Using Jackson tree model APIs to query and update data
          2. Processing JSON with Jackson data binding APIs
            1. Simple Jackson data binding with generalized objects
            2. Full Jackson data binding with specialized objects
          3. Processing JSON with Jackson streaming APIs
            1. Using Jackson streaming APIs to parse JSON data
            2. Using Jackson streaming APIs to generate JSON
        5. Using the Gson API for processing JSON
          1. Processing JSON with object model APIs in Gson
            1. Generating the object model from the JSON representation
            2. Generating the parameterized Java collection from the JSON representation
            3. Generating the JSON representation from the object model
          2. Processing JSON with Gson streaming APIs
            1. Reading JSON data with Gson streaming APIs
            2. Writing JSON data with Gson streaming APIs
        6. Summary
      11. 3. Introducing the JAX-RS API
        1. An overview of JAX-RS
        2. JAX-RS annotations
          1. Specifying the dependency of the JAX-RS API
          2. Using JAX-RS annotations to build RESTful web services
            1. Annotations for defining a RESTful resource
              1. @Path
                1. Specifying the @Path annotation on a resource class
                2. Specifying the @Path annotation on a resource class method
                3. Specifying variables in the URI path template
                4. Restricting values for path variables with regular expressions
            2. Annotations for specifying request-response media types
              1. @Produces
              2. @Consumes
            3. Annotations for processing HTTP request methods
              1. @GET
              2. @PUT
              3. @POST
              4. @DELETE
              5. @HEAD
              6. @OPTIONS
            4. Annotations for accessing request parameters
              1. @PathParam
              2. @QueryParam
              3. @MatrixParam
              4. @HeaderParam
              5. @CookieParam
              6. @FormParam
              7. @DefaultValue
              8. @Context
              9. @BeanParam
              10. @Encoded
        3. Returning additional metadata with responses
        4. Understanding data binding rules in JAX-RS
          1. Mapping the path variable with Java types
          2. Mapping the request and response entity body with Java types
            1. Using JAXB to manage the mapping of the request and response entity body to Java objects
        5. Building your first RESTful web service with JAX-RS
          1. Setting up the environment
          2. Building a simple RESTful web service application using NetBeans IDE
          3. Adding CRUD operations on the REST resource class
        6. Client APIs for accessing RESTful web services
          1. Specifying a dependency of the JAX-RS client API
          2. Calling REST APIs using the JAX-RS client
            1. Simplified client APIs for accessing REST APIs
        7. Summary
      12. 4. Advanced Features in the JAX-RS API
        1. Understanding subresources and subresource locators in JAX-RS
          1. Subresources in JAX-RS
          2. Subresource locators in JAX-RS
        2. Exception handling in JAX-RS
          1. Reporting errors using ResponseBuilder
          2. Reporting errors using WebApplicationException
        3. Reporting errors using application exceptions
          1. Mapping exceptions to a response message using ExceptionMapper
        4. Introducing validations in JAX-RS applications
          1. A brief introduction to Bean Validation
          2. Building custom validation constraints
          3. What happens when Bean Validation fails in a JAX-RS application?
        5. Supporting custom request-response message formats
          1. Building a custom entity provider
            1. Marshalling Java objects to the CSV representation with MessageBodyWriter
            2. Marshalling CSV representation to Java objects with MessageBodyReader
        6. Asynchronous RESTful web services
        7. Asynchronous RESTful web service client
        8. Managing HTTP cache in a RESTful web service
          1. Using the Expires header to control the validity of the HTTP cache
          2. Using Cache-Control directives to manage the HTTP cache
          3. Conditional request processing with the Last-Modified HTTP response header
          4. Conditional request processing with the ETag HTTP response header
          5. Conditional data update in RESTFul web services
        9. Understanding filters and interceptors in JAX-RS
          1. Modifying request and response parameters with JAX-RS filters
            1. Implementing server-side request message filters
              1. Postmatching server-side request message filters
              2. Prematching server-side request message filters
            2. Implementing server-side response message filters
            3. Implementing client-side request message filters
            4. Implementing client-side response message filters
          2. Modifying request and response message bodies with JAX-RS interceptors
            1. Implementing request message body interceptors
            2. Implementing response message body interceptors
          3. Managing the order of execution for filters and interceptors
          4. Selectively applying filters and interceptors on REST resources by using @NameBinding
          5. Dynamically applying filters and interceptors on REST resources using DynamicFeature
        10. Understanding the JAX-RS resource lifecycle
        11. Summary
      13. 5. Introducing the Jersey Framework Extensions
        1. Specifying dependencies for Jersey
        2. Programmatically configuring JAX-RS resources during deployment
          1. A quick look at the static resource configurations
        3. Modifying JAX-RS resources during deployment using ModelProcessor
          1. What is Jersey ModelProcessor and how does it work?
            1. A brief look at the ModelProcessor interface
        4. Building Hypermedia as the Engine of Application State (HATEOAS) APIs
          1. Formats for specifying JSON REST API hypermedia links
          2. Programmatically building entity body links using JAX-RS APIs
          3. Programmatically building header links using JAX-RS APIs
          4. Declaratively building links using Jersey annotations
            1. Specifying the dependency to use Jersey declarative linking
            2. Enable Jersey declarative linking feature for the application
            3. Declaratively adding links to resource representation
            4. Grouping multiple links using @InjectLinks
            5. Declaratively building HTTP link headers using @InjectLinks
        5. Reading and writing binary large objects using Jersey APIs
          1. Building RESTful web service for storing images
          2. Building RESTful web service for reading images
        6. Generating chunked output using Jersey APIs
          1. Jersey client API for reading chunked input
        7. Supporting Server Sent Event in RESTful web services
        8. Understanding the Jersey server-side configuration properties
        9. Monitoring RESTful web services using Jersey APIs
        10. Summary
      14. 6. Securing RESTful Web Services
        1. Securing and authenticating web services
        2. HTTP basic authentication
          1. Building JAX-RS clients with basic authentication
          2. Securing JAX-RS services with basic authentication
            1. Configuring JAX-RS application for basic authentication
              1. Defining groups and users in the GlassFish server
        3. HTTP digest authentication
        4. Securing RESTful web services with OAuth
          1. Understanding the OAuth 1.0 protocol
            1. Building the OAuth 1.0 client using Jersey APIs
          2. Understanding the OAuth 2.0 protocol
            1. Understanding the grant types in OAuth 2.0
            2. Building the OAuth 2.0 client using Jersey APIs
        5. Authorizing the RESTful web service accesses via the security APIs
          1. Using SecurityContext APIs to control access
          2. Using the javax.annotation.security annotations to control access with the Jersey framework
          3. Using Jersey's role-based entity data filtering
        6. Input validation
        7. Summary
      15. 7. The Description and Discovery of RESTful Web Services
        1. Introduction to RESTful web services
        2. Web Application Description Language
          1. An overview of the WADL structure
          2. Generating WADL from JAX-RS
          3. Generating the Java client from WADL
          4. Market adoption of WADL
        3. RESTful API Modeling Language
          1. An overview of the RAML structure
          2. Generating RAML from JAX-RS
            1. Generating RAML from JAX-RS via CLI
          3. Generating JAX-RS from RAML
            1. Generating JAX-RS from RAML via CLI
          4. A glance at the market adoption of RAML
        4. Swagger
          1. A quick overview of Swagger's structure
          2. An overview of Swagger APIs
          3. Generating Swagger from JAX-RS
            1. Specifying dependency to Swagger
            2. Configuring the Swagger definition
            3. Adding Swagger annotations on a JAX-RS resource class
          4. Generating Java client from Swagger
          5. A glance at the market adoption of Swagger
        5. Revisiting the features offered in WADL, RAML, and Swagger
        6. Summary
      16. 8. RESTful API Design Guidelines
        1. Identifying resources in a problem domain
        2. Transforming operations to HTTP methods
          1. Understanding the difference between PUT and POST
        3. Naming RESTful web resources
        4. Fine-grained and coarse-grained resource APIs
        5. Using header parameter for content negotiation
        6. Multilingual RESTful web API resources
        7. Representing date and time in RESTful web resources
        8. Implementing partial response
        9. Implementing partial update
        10. Returning modified resources to the caller
        11. Paging resource collection
        12. Implementing search and sort operations
        13. Using HATEOAS in response representation
          1. Hypertext Application Language
          2. RFC 5988 – Web Linking
        14. Versioning RESTful web APIs
          1. Including the version in resource URI – the URI versioning
          2. Including the version in a custom HTTP request header – HTTP header versioning
          3. Including the version in a HTTP Accept header – the media type versioning
          4. Hybrid approach for versioning APIs
        15. Caching RESTful web API results
          1. HTTP Cache-Control directive
          2. HTTP conditional requests
        16. Using HTTP status codes in RESTful web APIs
        17. Overriding HTTP methods
        18. Documenting RESTful web APIs
        19. Asynchronous execution of RESTful web APIs
        20. Microservice architecture style for RESTful web applications
        21. Using Open Data Protocol with RESTful web APIs
          1. A quick look at OData
            1. URI convention for OData-based REST APIs
            2. Reading resources
            3. Querying data
            4. Modifying data
            5. Relationship operations
        22. Summary
      17. A. Useful Features and Techniques
        1. Tools for building a JAX-RS application
        2. Integration testing of JAX-RS resources with Arquillian
          1. Adding Arquillian dependencies to the Maven-based project
          2. Configuring the container for running tests
          3. Adding Arquillian test classes to the project
          4. Running Arquillian tests
        3. Implementing PATCH support in JAX-RS resources
          1. Defining the @PATCH annotation
          2. Defining a resource method to handle HTTP PATCH requests
        4. Using third-party entity provider frameworks with Jersey
          1. Transforming the JPA model in to OData-enabled RESTful web services
        5. Packaging and deploying JAX-RS applications
          1. Packaging JAX-RS applications with an Application subclass
          2. Packaging the JAX-RS applications with web.xml and an Application subclass
            1. Configuring web.xml for a servlet 2.x container
            2. Configuring web.xml for a Servlet 3.x container
          3. Packaging the JAX-RS applications with web.xml and without an Application subclass
            1. Configuring web.xml for the servlet 2.x container
            2. Configuring web.xml for the servlet 3.x container
        6. Summary
      18. Index