REST has quickly become the de facto standard for building web services on the web because REST services are easy to build and easy to consume.

A much larger discussion can be had about how REST fits in the world of microservices.However, for this tutorial, we look only at building RESTful services.

Why REST? REST embraces the precepts of the web, including its architecture, benefits, and everything else. This is no surprise, given that its author (Roy Fielding) was involvedin probably a dozen specs which govern how the web operates.

What benefits? The web and its core protocol, HTTP, provide a stack of features:

• Suitable actions (GET,POST,PUT,DELETE, and others)

• Caching

• Redirection and forwarding

• Security (encryption and authentication)

These are all critical factors when building resilient services. However, that is not all. The web is built out of lots of tiny specs. This architecture lets it easily evolve without getting bogged down in "standards wars".

Developers can draw upon third-party toolkits that implement these diverse specs and instantly have both client and server technology at their fingertips.

By building on top of HTTP, REST APIs provide the means to build:

• Backwards compatible APIs

• Evolvable APIs

• Scaleable services

• Securable services

• A spectrum of stateless to stateful services

Note that REST, however ubiquitous, is not a standardper se but an approach, a style, a set ofconstraints on your architecture that can help you build web-scale systems. This tutorial uses the Spring portfolio to build a RESTful service while takin advantage of the stackless features of REST.

To get started, you need:

• A favorite text editor or IDE, such as:

  • IntelliJ IDEA

  • VSCode

• Java 17 or later

As we work through this tutorial, we useSpring Boot. Go toSpring Initializr and add the following dependencies to a project:

• Spring Web

• Spring Data JPA

• H2 Database

Change the Name to "Payroll" and then chooseGenerate Project. A.zip file downloads. Unzip it. Inside, you should find a simple, Maven-based project that includes apom.xml build file. (Note: You can use Gradle. The examples in this tutorial will be Maven-based.)

To complete the tutorial, you could start a new project from scratch or you could look at thesolution repository in GitHub.

If you choose to create your own blank project, this tutorial walks you through building your application sequentially. You do not need multiple modules.

Rather than providing a single, final solution, thecompleted GitHub repository uses modules to separate the solution into four parts.The modules in the GitHub solution repository build on one another, with thelinks module containing the final solution.The modules map to the following headers:

• The Story So Far (nonrest)

• Spring HATEOAS (rest)

• Simplifying Link Creation (evolution)

• Building links into your REST API (links)

We start off with the simplest thing we can construct.In fact, to make it as simple as possible, we can even leave out the concepts of REST.(Later on, we add REST, to understand the difference.)

Big picture: We are going to create a simple payroll service that manages the employees of a company. We store employee objects in a (H2 in-memory) database, and access them (through something called JPA). Then we wrap that with something that allows access over the internet (called the Spring MVC layer).

The following code defines anEmployee in our system.

Despite being small, this Java class contains much:

• @Entity is a JPA annotation to make this object ready for storage in a JPA-based data store.

• id,name, androle are attributes of ourEmployee domain object.id is marked with more JPA annotations to indicate that it is the primary key and is automatically populated by the JPA provider.

• A custom constructor is created when we need to create a new instance but do not yet have anid.

With this domain object definition, we can now turn toSpring Data JPA to handle the tedious database interactions.

Spring Data JPA repositories are interfaces with methods that support creating, reading, updating, and deleting records against a back end data store. Some repositories also support data paging and sorting, where appropriate. Spring Data synthesizes implementations based on conventions found in the naming of the methods in the interface.

Spring makes accessing data easy. By declaring the followingEmployeeRepository interface, we can automatically:

• Create new employees

• Update existing employees

• Delete employees

• Find employees (one, all, or search by simple or complex properties)

To get all this free functionality, all we have to do is declare an interface that extends Spring Data JPA’sJpaRepository, specifying the domain type asEmployee and theid type asLong.

Spring Data’srepository solution makes it possible to sidestep data store specifics and, instead, solve a majority of problems by using domain-specific terminology.

Believe it or not, this is enough to launch an application! A Spring Boot application is, at a minimum, apublic static void main entry-point and the@SpringBootApplication annotation. This tells Spring Boot to help out wherever possible.

@SpringBootApplication is a meta-annotation that pulls incomponent scanning,auto-configuration, andproperty support. We do not diveinto the details of Spring Boot in this tutorial. However, in essence, it starts a servlet container and serves up our service.

An application with no data is not very interesting, so we preload that it has data. The following class gets loaded automatically by Spring:

What happens when it gets loaded?

• Spring Boot runs ALLCommandLineRunner beans once the application context is loaded.

• This runner requests a copy of theEmployeeRepository you just created.

• The runner creates two entities and stores them.

Right-click andRunPayRollApplication, and you get:

This is not thewhole log, but only the key bits of preloading data.

To wrap your repository with a web layer, you must turn to Spring MVC. Thanks to Spring Boot, you need add only a little code. Instead, we can focus on actions:

• @RestController indicates that the data returned by each method is written straight into the response body instead of rendering a template.

• AnEmployeeRepository is injected by constructor into the controller.

• We have routes for each operation (@GetMapping,@PostMapping,@PutMapping and@DeleteMapping, corresponding to HTTPGET,POST,PUT, andDELETE calls). (We recommend reading each method and understanding what they do.)

• EmployeeNotFoundException is an exception used to indicate when an employee is looked up but not found.

When anEmployeeNotFoundException is thrown, this extra tidbit of Spring MVC configuration is used to render anHTTP 404 error:

• @RestControllerAdvice signals that this advice is rendered straight into the response body.

• @ExceptionHandler configures the advice to only respond when anEmployeeNotFoundException is thrown.

• @ResponseStatus says to issue anHttpStatus.NOT_FOUND — that is, anHTTP 404 error.

• The body of the advice generates the content. In this case, it gives the message of the exception.

To launch the application, you can right-click thepublic static void main inPayRollApplication and selectRun from your IDE.

Alternatively, Spring Initializr creates a Maven wrapper, so you can run the following command:

Alternatively, you can use your installed Maven version, as follows:

When the app starts, you can immediately interrogate it, as follows:

Doing so yields the following:

You can see the pre-loaded data in a compacted format.

Now try to query a user that doesn’t exist, as follows:

When you do so, you get the following output:

This message nicely shows anHTTP 404 error with the custom message:Could not find employee 99.

It is not hard to show the currently coded interactions.

To create a newEmployee record, use the following command in a terminal (the$ at the beginning signifies that what follows it is a terminal command):

Then it stores the newly created employee and sends it back to us:

You can update the user. For example, you can change the role:

Now we can see the change reflected in the output:

Finally, you can delete users, as follows:

This is all well and good, but do we have a RESTful service yet? (The answer is no.)

What’s missing?

So far, you have a web-based service that handles the core operations that involve employee data. However, that is not enough to make things "RESTful".

• Pretty URLs, such as`/employees/3`, aren’t REST.

• Merely usingGET,POST, and so on is not REST.

• Having all the CRUD operations laid out is not REST.

In fact, what we have built so far is better described asRPC (Remote Procedure Call), because there is no way to know how to interact with this service. If you published this today, you wouldd also have to write a document or host a developer’s portal somewhere with all the details.

This statement of Roy Fielding’s may further lend a clue to the difference betweenREST andRPC:

I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.

What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?

The side effect of nnot including hypermedia in our representations is that clients must hard-code URIs to navigate the API. This leads to the same brittle nature that predated the rise of e-commerce on the web. It signifies that our JSON output needs a little help.

Now we can introduceSpring HATEOAS, a Spring project aimed at helping you write hypermedia-driven outputs. To upgrade your service to being RESTful, add the following to your build:

This tiny library gives us the constructs that define a RESTful service and then render it in an acceptable format for client consumption.

A critical ingredient to any RESTful service is addinglinks to relevant operations. To make your controller more RESTful, add links like the following to the existingone method inEmployeeController:

You also need to include new imports:

This is very similar to what we had before, but a few things have changed:

• The return type of the method has changed fromEmployee toEntityModel<Employee>.EntityModel<T> is a generic container from Spring HATEOAS that includes not only the data but a collection of links.

• linkTo(methodOn(EmployeeController.class).one(id)).withSelfRel() asks that Spring HATEOAS build a link to theone method ofEmployeeController and flag it as aself link.

• linkTo(methodOn(EmployeeController.class).all()).withRel("employees") asks Spring HATEOAS to build a link to the aggregate root,all(), and call it "employees".

What do we mean by "build a link?" One of Spring HATEOAS’s core types isLink. It includes aURI and arel (relation).Links are what empower the web. Before the World Wide Web, other document systems would render information or links, but it was the linking of documents WITH this kind of relationship metadata that stitched the web together.

Roy Fielding encourages building APIs with the same techniques that made the web successful, and links are one of them.

If you restart the application and query the employee record ofBilbo, you get a slightly different response than earlier:

This decompressed output shows not only the data elements you saw earlier (id,name, androle) but also a_links entry that contains two URIs. This entire document is formatted usingHAL.

HAL is a lightweightmediatype that allows encoding not only data but also hypermedia controls, alerting consumers to other parts of the API to which they can navigate. In this case,there is a "self" link (kind of like athis statement in code) along with a link back to theaggregate root.

To make the aggregate root also be more RESTful, you want to include top level links while also including any RESTful components within.

So we modify the following (located in thenonrest module of the completed code):

We want the following (located in therest module of the completed code):

That method, which used to be merelyrepository.findAll(), is "all grown up."" Not to worry. Now we can unpack it.

CollectionModel<> is another Spring HATEOAS container. It is aimed at encapsulating collections of resources instead of a single resource entity, such asEntityModel<> from earlier.CollectionModel<>, too, lets you include links.

Do not let that first statement slip by. What does "encapsulating collections" mean? Collections of employees?

Not quite.

Since we are talking REST, it should encapsulate collections ofemployee resources.

That is why you fetch all the employees but then transform them into a list ofEntityModel<Employee> objects. (Thanks Java Streams!)

If you restart the application and fetch the aggregate root, you can see what it looks like now:

For this aggregate root, which serves up a collection of employee resources, there is a top-level"self"link. The"collection" is listed underneath the"_embedded" section. This is how HAL represents collections.

Each individual member of the collection has their information as well as related links.

What is the point of adding all these links? It makes it possible to evolve REST services over time.Existing links can be maintained while new links can be added in the future.Newer clients may take advantage of the new links, while legacy clients can sustain themselves on the old links.This is especially helpful if services get relocated and moved around.As long as the link structure is maintained,clients can still find and interact with things.

In the code earlier, did you notice the repetition in single employee link creation? The code to providea single link to an employee, as well as to create an "employees" link to the aggregate root, was showntwice. If that raised a concern, good! There’s a solution.

You need to define a function that convertsEmployee objects toEntityModel<Employee> objects.While you could easily code this method yourself, SpringHATEOAS’sRepresentationModelAssembler interface does the work for you. Create a new classEmployeeModelAssembler:

This simple interface has one method:toModel(). It is based on converting a non-model object(Employee) into a model-based object (EntityModel<Employee>).

All the code you saw earlier in the controller can be moved into this class. Also, by applying SpringFramework’s@Component annotation, the assembler is automatically created when the app starts.

To leverage this assembler, you have only to alter theEmployeeController by injecting the assembler in the constructor:

From here, you can use that assembler in the single-item employee methodone that already exists inEmployeeController:

This code is almost the same, except that, instead of creating theEntityModel<Employee> instance here, youdelegate it to the assembler. Maybe that is not impressive.

Applying the same thing in the aggregate root controller method is more impressive. This change is also to theEmployeeController class:

The code is, again, almost the same. However, you get to replace all thatEntityModel<Employee> creation logic withmap(assembler::toModel). Thanks to Java method references, it is super easy to plug in and simplify your controller.

At this stage, you have created a Spring MVC REST controller that actually produces hypermedia-powered content. Clients that do not speak HAL can ignore the extra bits while consuming the pure data. Clients that do speak HAL can navigate your empowered API.

But that is not the only thing needed to build a truly RESTful service with Spring.

With one additional library and a few lines of extra code, you have added hypermedia to your application.But that is not the only thing needed to make your service RESTful. An important facet of REST is the factthat it is neither a technology stack nor a single standard.

REST is a collection of architectural constraints that, when adopted, make your application much moreresilient. A key factor of resilience is that when you make upgrades to your services, your clientsdo not suffer downtime.

In the "olden" days, upgrades were notorious for breaking clients. In other words, an upgrade to theserver required an update to the client. In this day and age, hours or even minutes of downtime spentdoing an upgrade can cost millions in lost revenue.

Some companies require that you present management with a plan to minimize downtime. In the past, youcould get away with upgrading at 2:00 a.m. on a Sunday when load was at a minimum. But in today’sInternet-based e-commerce with international customers in other time zones, such strategies are not as effective.

SOAP-based services andCORBA-based services were incredibly brittle. It was hard to roll out aserver that could support both old and new clients. With REST-based practices, it is much easier,especially using the Spring stack.

So far, you have built an evolvable API with bare bones links.To grow your API and better serve your clients, you need to embrace the concept ofHypermedia as the Engine of Application State.

What does that mean? This section explores it in detail.

Business logic inevitably builds up rules that involve processes.The risk of such systems is we often carry such server-side logic into clients and build up strong coupling.REST is about breaking down such connections and minimizing such coupling.

To show how to cope with state changes without triggering breaking changes in clients, imagine adding a system that fulfills orders.

As a first step, define a newOrder record:

• The class requires a JPA@Table annotation that changes the table’s name toCUSTOMER_ORDER becauseORDER is not a valid name for table.

• It includes adescription field as well as astatus field.

Orders must go through a certain series of state transitions from the time a customer submits an order and it is eitherfulfilled or cancelled. This can be captured as a Javaenum calledStatus:

Thisenum captures the various states anOrder can occupy. For this tutorial, we keep it simple.

To support interacting with orders in the database, you must define a corresponding Spring Data repository calledOrderRepository:

We also need to create a new exception class calledOrderNotFoundException:

With this in place, you can now define a basicOrderController with the required imports:

• It contains the same REST controller setup as the controllers you have built so far.

• It injects both anOrderRepository and a (not yet built)OrderModelAssembler.

• The first two Spring MVC routes handle the aggregate root as well as a single itemOrder resource request.

• The third Spring MVC route handles creating new orders, by starting them in theIN_PROGRESS state.

• All the controller methods return one of Spring HATEOAS’sRepresentationModel subclasses to properly render hypermedia (or a wrapper around such a type).

Before building theOrderModelAssembler, we should discuss what needs to happen. You are modeling the flow of states betweenStatus.IN_PROGRESS,Status.COMPLETED, andStatus.CANCELLED. A natural thing when serving up such data to clients is tolet the clients make the decision about what they can do, based on this payload.

But that would be wrong.

What happens when you introduce a new state in this flow? The placement of various buttons on the UI would probably be erroneous.

What if you changed the name of each state, perhaps while coding international support and showing locale-specific text for each state?That would most likely break all the clients.

EnterHATEOAS orHypermedia as the Engine of Application State. Instead of clients parsing the payload, give them linksto signal valid actions. Decouple state-based actions from the payload of data. In other words, whenCANCEL andCOMPLETE are valid actions,you should dynamically add them to the list of links. Clients need to show users the corresponding buttons only when the links exist.

This decouples clients from having to know when such actions are valid, reducing the risk of the server and its clients gettingout of sync on the logic of state transitions.

Having already embraced the concept of Spring HATEOASRepresentationModelAssembler components, theOrderModelAssembleris the perfect place to capture the logic for this business rule:

This resource assembler always includes theself link to the single-item resource as well as a link back to the aggregate root.However, it also includes two conditional links toOrderController.cancel(id) as well asOrderController.complete(id) (not yet defined). Theselinks are shown only when the order’s status isStatus.IN_PROGRESS.

If clients can adopt HAL and the ability to read links instead of simply reading the data of plain old JSON, they can tradein the need for domain knowledge about the order system. This naturally reduces coupling between client and server. Italso opens the door to tuning the flow of order fulfillment without breaking clients in the process.

To round out order fulfillment, add the following to theOrderController for thecancel operation:

It checks theOrder status before letting it be cancelled. If it is not a valid state, it returns anRFC-7807Problem,a hypermedia-supporting error container. If the transition is indeed valid, it transitions theOrder toCANCELLED.

Now we need to add this to theOrderController as well for order completion:

This implements similar logic to prevent anOrder status from being completed unless in the proper state.

Let’s updateLoadDatabase to pre-load someOrder objectss along with theEmployee objects it was loading before.

Now you can test. Restart your application to make sure you are running the latest code changes. To use the newly minted order service, you can perform a few operations:

This HAL document immediately shows different links for each order, based upon its present state.

• The first order, beingCOMPLETED, only has the navigational links. The state transition links are not shown.

• The second order, beingIN_PROGRESS, additionally has thecancel link as well as thecomplete link.

Now try cancelling an order:

This response shows anHTTP 200 status code, indicating that it was successful. The response HAL document shows that order in itsnew state (CANCELLED). Also, the state-altering links gone.

Now try the same operation again:

You can see anHTTP 405 Method Not Allowed response.DELETE has become an invalid operation. TheProblem responseobject clearly indicates that you are not allowed to "cancel" an order already in the "CANCELLED" status.

Additionally, trying to complete the same order also fails:

With all this in place, your order fulfillment service is capable of conditionally showing what operations are available. Italso guards against invalid operations.

By using the protocol of hypermedia and links, clients can be made sturdier and be less likely to break simply becauseof a change in the data. Spring HATEOAS eases building the hypermedia you need to serve to your clients.

Throughout this tutorial, you have engaged in various tactics to build REST APIs. As it turns out, REST is not just about pretty URIs and returning JSON instead of XML.

Instead, the following tactics help make your services less likely to break existing clients you may or may not control:

• Do not remove old fields. Instead, support them.

• Use rel-based links so clients need not hard code URIs.

• Retain old links as long as possible. Even if you have to change the URI, keep the rels so that older clientshave a path to the newer features.

• Use links, not payload data, to instruct clients when various state-driving operations are available.

It may appear to be a bit of effort to build upRepresentationModelAssembler implementations for eachresource type and to use these components in all of your controllers. However, this extra bit of server-sidesetup (made easy thanks to Spring HATEOAS) can ensure the clients you control (and more importantly, thoseyou do not control) can upgrade with ease as you evolve your API.

This concludes our tutorial on how to build RESTful services using Spring. Each section of this tutorial is managed as a separatesubproject in a single github repo:

• nonrest — Simple Spring MVC app with no hypermedia

• rest — Spring MVC + Spring HATEOAS app with HAL representations of each resource

• evolution — REST app where a field is evolved but old data is retained for backward compatibility

• links — REST app where conditional links are used to signal valid state changes to clients

To view more examples of using Spring HATEOAS, seehttps://github.com/spring-projects/spring-hateoas-examples.

To do some more exploring, check out the following video by Spring teammate Oliver Drotbohm:

https://raw.githubusercontent.com/spring-guides/getting-started-macros/master/footer.adoc