Your Cart
No products in the cart.

It's not hard to create a RESTful web service in Java. In fact, frameworks like Spring Boot, the Eclipse MicroProfile and Jakarta Enterprise Edition make the development of RESTful Java applications relatively easy.
But the problem with many RESTful web services isn't their development but their design. This RESTful APIs tutorial addresses the web service design issue and sheds light on the common mistakes software developers make when they conjure up a RESTful API.
Designers have two key elements to consider in the development of a RESTful Java API:
The first important principle this RESTful APIs tutorial asserts is that resources should always be accessed through URLs that uniquely identify them.
This should be a novel concept for anyone who has ever used a web browser. When we access a webpage or download a web-based PDF file, we point our browser to a URL that identifies that resource. The same concept applies when one accesses server-side resources with a RESTful Java web service. If a jQuery or Angular client needs to manipulate a resource, there should be a unique URL that the associated JavaScript code can use to identify the RESTful resource in question.

I often prototype software development concepts with a little rock-paper-scissors application. In that application I typically code a component that keeps track of wins, losses and ties. An effective RESTful API that allows users to interact with the score would include the following URL in its design:
When users access this URL -- through the browser, through a RESTful JavaScript application or through a Spring Boot MVC component -- they'll receive a representation of the current score. A RESTful Java API that supports JSON might return a result such as this:
If a RESTful JavaScript client is only interested in wins, the URL should follow a predictable format where wins is a subresource of the score:
In fact, returning the number of wins in JSON format is probably overkill. Just returning the number of wins as basic text makes the result easily consumed by all clients, regardless of whether they can parse JSON or not. So the following would be preferable:
Losses and ties should follow a similar RESTful URL format:
All of the RESTful API examples presented so far assume a simple GET invocation. The HTTP protocol provides a number of different methods to interact with a RESTful resource though a URL. When presented with a URL, servers generally assume it's a GET request. However, a RESTful API designer should consider at least three other HTTP methods -- namely, POST, PUT and DELETE.
To tackle HTTP method, there are important RESTful design rules to follow. RESTful Java API designers tend to go astray if they violate these rules.
The first rule is that GET invocations can never change the state of any RESTful resource on the server. Our RESTful API fully complies with that rule.
While not exactly a hard-and-fast rule, PUT and DELETE methods roughly map to the concept of save and delete. If designers want to delete a resource from the server, they should use the HTTP DELETE method. If they need a new resource created or need to update an existing resource, they should use the PUT method.
The PUT and DELETE methods are relatively straightforward for saving and deleting data. It's the other PUT and DELETE rule where RESTful Java API designers tend to run into trouble. This second rule demands idempotency from HTTP methods.
If something is idempotent, it can be done repeatedly, and the result will always be the same.
For example, imagine a client made a RESTful DELETE request to remove record 271. That call could be made once, or it could be made 100 times. The end result will always be the same -- so long, record 271. This scenario below is idempotent.
Contrast that with a request to delete the 10 oldest records in the database.
With this example, the RESTful URL would leave the database in a different state with each new invocation -- right up to the point where every record in the database is deleted. This method is not idempotent and thus violates a fundamental RESTful API principle.
The PUT method must also be idempotent. So, if one needs to change the number of wins from the current value in the database to 10, a good RESTful Java API would look like this:
One could call this method over and over again, and after each invocation, the server would be left in the same state. The number of wins would be 10. This RESTful Java API is idempotent. Contrast that with a method that adds 10 wins each time it is invoked:
This method is not idempotent because, with each invocation, the number of wins jumps to a new value. The number of wins might start at 10 the first time, 20 when invoked a second time and 30 the next. The final state of the resource is unpredictable with this method. It is not idempotent and not good RESTful API design.
Technically speaking, query parameters at the end of a URL should be used for just that: querying. In this example, we are using a query parameter to pass a payload to the server. Doing so makes the example simpler, but it also violates the spirit of a query parameter's intended use. In a future RESTful API design tutorial, we will demonstrate how passing a JSON string as part of the payload during a PUT invocation is a better design than using query parameters.
So, we have seen in this RESTful APIs tutorial that the removal of the 10 oldest records from a database is a poor use of the DELETE method, and the incrementation of a number is a bad application of the PUT method. Does that mean we can't do these things with a RESTful API? No, not at all.
So far, this RESTful APIs tutorial establishes two very important rules:
But notice that we haven't said anything about the POST method. One can use the POST method in any scenario that falls outside of the aforementioned rules. So, if you want to prune the 10 oldest records from the database, use the POST method. If you want to increment the number of wins by 10, then, again, use the POST method. The POST method is the Swiss army knife of RESTful design.
Of course, there is a danger if you approach the POST method as a cure-all for every challenging corner case your RESTful API encounters. Just because you don't violate rules on idempotency or misuse the GET, PUT and DELETE methods, it doesn't mean you have properly designed a RESTful API. Overuse of the POST method is itself RESTful anti-pattern.
Far too often, you will see a supposedly RESTful system in which the designers have shoehorned every permutation of their API into a POST invocation. Just because you haven't violated important RESTful principles doesn't mean you have developed an effective RESTful API. The tendency toward heavy POST method use often occurs when RESTful API designers take a service-based approach to their problem domain. When you create RESTful APIs, it's important to always take a resource-based approach to your system.
There is much to learn, such as best practices for passing payload data to the server, how to structure URLs to identify resources and how to avoid the trap of taking a service-based approach to a resource-based design. We will cover those in subsequent RESTful APIs tutorials. But a strong foundation in structuring URLs and the proper use of HTTP methods is the basis of every beautiful resource-based API ever designed.
While plenty of developers entertain the idea of adopting a functional programming model, it's important to first know exactly ...
In this primer on SOLID, we'll examine the five principles this development ideology embodies, the practices they encourage and ...
Every software project proposal requires in-depth research into the technical aspects at play, but the business case for the ...
Docker ships a managed service that pushes container image builds to AWS and adds shared caches to customers' existing dev tools.
Using open source software raises concerns about security and intellectual property. Here's how to make sound decisions and avoid...
Apache JMeter and other load-testing tools can be used with Kubernetes to conduct stress tests to see how well an app performs in...
The cost of spot prices can be a risk-and-reward kind of strategy. Better understand the risks that come with Azure Spot VMs so ...
A successful FinOps team relies on clear team structure and roles, shared accountability and baseline measures of success. Use ...
PaaS is a good option for developers who want control over application hosting and simplified app deployment, but not all PaaS ...
HPE suspects that Cozy Bear, a Russian state-sponsored threat actor also known as Midnight Blizzard and Nobelium, breached its ...
To ensure successful adoption, IT leaders need to understand the benefits of SOAR tools, as well as potential disadvantages. ...
While other threats are likely to increase as well, the U.K.'s National Cyber Security Centre warns that threat actors will use ...
Many organizations struggle to manage their vast collection of AWS accounts, but Control Tower can help. The service automates ...
There are several important variables within the Amazon EKS pricing model. Dig into the numbers to ensure you deploy the service ...
AWS users face a choice when deploying Kubernetes: run it themselves on EC2 or let Amazon do the heavy lifting with EKS. See ...
All Rights Reserved, Copyright 2000 - 2024, TechTarget

Privacy Policy
Cookie Preferences
Do Not Sell or Share My Personal Information