How To Implement Rest Service In Java

In the modern world of interconnected software, web applications take become an indispensable asset. Foremost among these spider web applications is the Representational Land Transfer (REST) spider web service, with Java becoming one of the most pop implementation languages. Inside the Coffee REST ecosystem, in that location are two popular contenders: Java Enterprise Edition (JavaEE) and Spring. While both take their strengths and weaknesses, this article volition focus on Spring and create a uncomplicated order management RESTful web application using Spring 4. Although this management organization will be simple compared to the large-scale RESTful services plant today, information technology will nonetheless demonstrate the basic thought process, design decisions, and implementation tests required to create a Level 3 (hypermedia-driven) Spring Residuum web service.

By the cease of this article, we volition have created a fully functional Leap Residual club management system. While the source code illustrated in this article covers the essential aspects of the lodge management organisation, in that location are other components and lawmaking (such as exam cases) that support the chief service that are not shown. All of the source code, including these supporting aspects, can be institute in the post-obit GitHub repository:

The source code snippets in this article are not in-and-of-themselves sufficient for creating a fully functioning REST spider web service. Instead, they serve as a snapshot or reflection of the source code contained in the above repository. Therefore, every bit we walk through each pace in creating our Residual service, the source code in the above repository should be visited consistently and used as the authoritative reference for all design and implementation choices. For the residuum of this article, when we refer to our social club management organisation, we are actually referring to the Jump REST service contained in the above repository.

Prerequisite Noesis

It is expected that the reader has at least a novice understanding of dependency injection (DI), peculiarly DI using the Leap framework. Although we will explore the DI framework configurations used and the DI components utilized in our society direction arrangement, it is assumed that the reader has at least a conceptual understanding of the need for and premise of DI. For more information on DI in Spring, see the Spring Framework Guide and DZone's Leap Configuration Refcard.

This article also assumes that the reader has a foundational understanding of REST and RESTful web services. While nosotros volition deep swoop into the design and implementation intricacies of creating a Balance spider web service in Spring, nosotros will not focus on the conceptual aspects of Residual (such equally the use of an HTTP GET or Post telephone call). For more information on RESTful spider web services, see DZone'south Foundations of RESTful Architecture Refcard and RESTful Spider web Services past Leonard Richardson and Sam Ruby.

Development Cycle and Tools

Our order direction system was created using Exam Driven Development (TDD), where tests were created start and each design conclusion and implemented component was focused on passing the created examination cases. This not merely resulted in a simple ready of classes, simply a more easily distinguishable set of components. For example, persistence logic and domain logic are not intertwined. Autonomously from the process used to create the service, at that place are too numerous tools used to build, test, and deploy the system, including:

• Bound Model-View-Controller (MVC): the core framework of our web service; this framework provides the necessary annotations and structure required to create our Rest endpoints and serve these endpoints over HTTP.
• Spring Boot: a convention-over-configuration framework that removes a majority of the boilerplate Spring code and configuration; this framework allows us to develop and launch of web service with a fraction of the hassle of a standard Spring web service.
• Apache Maven: a build and dependency management tool that is used to build, execute tests, and parcel our web service into a Java Annal (JAR) file that will exist executed to run our RESTful web service.
• JUnit: an automated unit testing framework that will be used for unit of measurement and integration tests, as well as to automate the execution of our credence tests.
• Cucumber: an automatic credence testing framework that allows united states of america to create text-based acceptance criteria and exercise our web service to ensure that all top-level functionality is correct during the evolution of the service.
• Java eight: at the fourth dimension of writing, the latest version of Java; nosotros will utilise the streams API to reduce the code needed to filter through the domain objects in our organisation.
• GitHub: a free hosting service for Git-based projects; our spider web service will be hosted hither and the commit history for the web service tin exist viewed here.
• Travis Continuous Integration (CI): a gratuitous continuous integration platform that executes the automated tests in order of web service each time a commit is pushed to our GitHub repository; the build and examination history of our web service can be viewed hither.

Although nosotros are using a wide array of frameworks and tools, each has a very important task when building our web service. Before we leap into the implementation, though, we commencement need to devise a blueprint for our gild direction system.

Designing the Web Service

The first step to designing our web service is deciding on what we want the service to accomplish. Since we are required to process orders, the definition of an order (i.due east. creating a domain model) is a practiced identify to start. Each guild that we procedure should accept an identifier (ID) so that nosotros tin can uniquely bespeak to it, a description that describes the order in a human-readable form, a cost, and a completion status.

Note that the toll is non a trivial issue to bargain with in software: It is very easy to lose rail of cents and make simple rounding errors. In order to avoid these subliminal issues, we will simply store the toll for our order in cents. This allows u.s. to remove the decimal place and perform elementary arithmetics without worrying that nosotros will lose a penny in the mix.

Using this unproblematic definition of an order, we devise the following domain model:

With our society designed, we can motility onto designing how we volition betrayal our orders through our RESTful web service. Using the standard HTTP verbs, nosotros tin rapidly come up with a set of Residue endpoints that cover the usual Create, Read, Update, and Delete (Grime) operations:

HTTP Verb	URL	Clarification
GET	/order	Obtains the list of all orders currently created in the organisation. If the listing is successfully obtained, the list of existing orders is returned, along with an HTTP 200 (OK) condition.
POST	/order	Creates a new order. This request should deport a request body that includes the data that should be associated with the newly created society. If the order is created, an HTTP 201 (Created) status is returned along with the newly created order in the response trunk.
Get	/order/{id}	Obtains the social club associated with the given ID. If no order exists, an HTTP 404 (Not Constitute) condition is returned. If the lodge can exist found, an HTTP 200 condition is returned and the response body contains the data associated with the order.
PUT	/order/{id}	Updates an existing order. If no order with the given ID can be institute, an HTTP 404 status is returned. If an order exists with the given ID and the request body contains valid updates to the order, the order is updated and the updated order is returned in the response trunk, along with an HTTP 200 condition.
DELETE	/order/{id}	Deletes an order with the given ID. If no order exists, an HTTP 404 status is returned. If the order exists, information technology is deleted, and an HTTP 204 (No Content) status is returned.

It is important to note that we should not but enumerate the REST endpoints nosotros intended to create, simply also include the expected beliefs if the endpoint successfully completes the asking or if it fails to do so. For example, if a client requests to update a non-existent guild, nosotros should return a 404 error to inform the client that this resources does not exist. If we successfully update the resources, we should return a 200 status to inform the client that its request was successfully completed.

At this point, it is also useful to think nearly what the response bodies for the various Residual endpoints will await like. Due to its simplicity, nosotros will consume Javascript Object Notation (JSON) objects in the request bodies we receive and produce JSON objects in the response bodies we ship, respectively. For example, if nosotros follow our domain model, the response body for getting an order with a specified ID would resemble:

          {     "id": 1,     "description": "Some sample gild",     "costInCents": 250,     "consummate": false }        

We volition see later on in this commodity that other attributes, such as hypermedia links, will as well be included. Irrespective of hypermedia link, thinking about the expected asking and response bodies for our REST endpoints allows usa to devise test cases in advance that ensure nosotros are handling and producing the expected results when we implement our Residue endpoints.

With our domain model and REST endpoints defined, we can move to the terminal piece of the puzzle: How to shop our orders. For example, when we create a new order, we need some means of storing that society so that a customer, at some future time, can call back the created society.

In a true Residuum web service, we would determine on the all-time database or persistence framework that supports our domain model and design a persistence layer interface to apply to collaborate with this database. For example, we could select a Neo4j database if our data was well-suited for a graph domain model, or MongoDB if our domain model fits nicely into collections. In the case of our system, for simplicity, nosotros will use an in-memory persistence layer. Although in that location are various useful in-memory databases, our model is simple enough to create the in-retentivity database ourselves. In doing and then, nosotros volition see the bones functionality of a database fastened to a REST service, also as understand the simple interfaces that are common among repositories in RESTful services.

Abstracting Our Design

At this betoken in our design, we have three detached sections of our system: (1) a domain model, (2) a series of Rest endpoints, and (3) a ways of storing our domain objects, or a persistence layer. This set of three sections is so common, it has its own name: A 3-Tier awarding. Whatsmore, Martin Fowler has written an entire volume, Patterns of Enterprise Architecture, on the patterns that surround this application architecture. The three tiers in this architecture are (one) presentation, (2) domain, and (3) information source (used interchangeably with persistence layer). In our example, our REST endpoints map to the presentation layer, our guild domain model maps to the domain layer, and our in-memory database maps to the information source layer.

Although these three layers are ordinarily depicted with 1 stacked on top of the other, with the presentation layer at the top, closest to the user, the domain layer in the middle, and the data source layer on the bottom, it tin can be more helpful to look at this architecture in terms of its interactions, as illustrated in the following diagram.

At that place is an important addition that is made to our architecture: Domain objects are non sent direct to the user. Instead, they are wrapped in resource and the resource are provided to the user. This provides a level of indirection between the domain object and how we present the domain object to the user. For example, if nosotros wish to nowadays the user with a different name for a field in our domain model (say orderName instead of just name), we can do and so using a resources. Although this level of indirection is very useful in decoupling our presentation from the domain model, it does let duplication to sneak in. In near cases, the resource will resemble the interface of the domain object, with a few minor additions. This issue is addressed later when we implement our presentation layer.

The resource object too provides an apt identify for usa to introduce our hypermedia links. According to the Richardson model for Balance web services, hypermedia-driven services are the highest adequacy level of a Balance application and provide of import information associated with the resource data. For example, we tin can provide links for deleting or updating the resource, which removes the demand for the client consuming our Residuum web service to know the Balance endpoints for these actions. In practice, the returned resource (deserialized to JSON) may resemble the following:

          {     "id": 1,     "clarification": "Some sample order",     "costInCents": 250,     "complete": false     "_links": {         "self": {             "href": "http://localhost:8080/order/1"         },         "update": {             "href": "http://localhost:8080/order/i"         },         "delete": {             "href": "http://localhost:8080/lodge/i"         }     } }        

Given these links, the consumer is no longer required to build the URLs for the update, delete, or cocky-reference Remainder endpoints. Instead, information technology can but use the links provided in our hypermedia-driven response. Non only does this reduces the logic necessary for interacting with our REST web service (no longer exercise the URLs need to be built), only it also encapsulates the logic for the construction of the URLs. For example, suppose we change our Residue service to require a query parameter, such every bit sorting: if nosotros provide the links to the consumer, we tin accommodate for that change, without making whatever changes to the consumer:

          {     "id": 1,     "description": "Some sample order",     "costInCents": 250,     "complete": false     "_links": {         "self": {             "href": "http://localhost:8080/guild/1?sorting=default"         },         "update": {             "href": "http://localhost:8080/gild/one?sorting=default"         },         "delete": {             "href": "http://localhost:8080/order/one?sorting=default"         }     } }        

Although generating these links could be tiresome and subject field to a large number of bugs (i.e. what if the IP accost of the machine hosting the spider web service changes?), the Spring Hypermedia as the Engine of Application Land (HATEOAS, commonly pronounced hay-tee-os) framework provides numerous classes and builders that permit us to create these links with ease. This topic will be explored further when nosotros delve into the implementation of our presentation layer.

Before moving to the implementation of our web service, nosotros must pull our design together and devise a plan of action to create it. At the moment, we have a single domain object, Club, instances of whom will be persisted in an in-retention database and served up (inside a resources) to clients using our REST endpoints. This design leaves united states of america with four main steps:

1. Implement the domain model
   • Create the Order domain class
2. Implement the information source layer
   • Create an in-retentiveness database
   • Implement the CRUD operations for the Club domain class
3. Implement the presentation layer
   • Create the Remainder endpoints
   • Create the Lodge resource
   • Create assembler to construct an Gild resources with proper HATEOAS links
4. Pull the application together
   • Create the main method that will run the application

In Role 2, we will piece of work on implementing the data source and domain layers, which will lay the foundation for implementing the RESTful interface of our spider web service.

Originally published September 2017

Further Reading

Creating a Residual Web Service With Java and Spring (Part 2)

Build a Residuum Web Service Using Spring

Step-by-Step Spring Boot RESTful Web Service Complete Case

Topics:

jump, mvc, spider web dev, java 8, balance spider web service

Opinions expressed by DZone contributors are their own.

Source: https://dzone.com/articles/creating-a-rest-api-with-java-and-spring

Posted by: bowlingbutersest1984.blogspot.com

Share this post