From ‘A’ to ‘Web App’: Build an API in Java
I’m writing this tutorial to fill a void that I have noticed. Building web apps is a top priority for people learning backend development, but I haven’t seen any Java or Spring Boot tutorials that provide a clear path to get you there quickly with the least amount of friction. Tutorials are either too trivial (Hello World API) to help you understand what you need to know; or they overwhelm beginners and assume too much about what you already know!
The only thing you should know already is Java, to an intermediate level, everything else I will cover along the way. If you are familiar with a topic already, you can skip ahead. This way, you know that there are no gaps in your knowledge, or blindspots in your learning path.
I will build a simple Web API with Spring Boot, which is a big step towards what you would build for an enterprise-grade application.
What is an API?
It is common now for companies to give access to their data through APIs. API stands for Application Programming Interface, it is a list of methods we can use to interact with a company’s backend systems over the internet. These methods are often referred to as web services.
Let’s look at an example of an API to clarify what it is exactly!
Twitter API Example
I’m guessing you know what Twitter is already, but let’s state what it is regardless, Twitter is a social micro-blogging website. It’s become more than that over time, now it’s where Donald Trump goes to vent! ✍😡
Twitter’s API reference gives you a long categorized list of methods. You can perform a wide range of actions on: tweets, direct messages, your personal account settings, and more. Almost everything you can do on the website is possible to do through the API. If you wanted to, you could use the API to build an entirely different front-end for Twitter, or a TwitterBot.
Let’s take an example of using the API, say we want to get all of the tweets from the timeline of @spiderman.
Looking through the list of methods, GET statuses/user_timeline appears to be the method that matches what we want. This is the method description:
We need to have a client application to execute the methods. I like to use Insomnia, but other popular applications are: cURL (a command-line tool), Postman (a collaboration platform for API Development), and Postwoman (a minimal open-source alternative to Postman).
If you are totally unfamiliar with HTTP, you can jump to the HTTP Basics section to get yourself up to speed. Looking at the method description, we need to provide 1 parameter in our HTTP request to get the data we want, this parameter is screen_name
.
To use Twitter’s API, you have to have a Twitter account, and register an application to obtain developer keys. When you interact with the API, you provide these developer keys to authenticate your identity. This ensures that only you can only perform actions on your own account data, and generally that you use the platform in a fair way.
You need to do some configuration in your Twitter account settings to get the developer keys. It’s not obvious to locate the place in the settings for this! I wont show you how here, the focus is to show you what an API is. Below is the request (on the left) and the response received (on the right).
You can see that our screen_name
parameter is appended to the URL in our request. We use a question mark to mark the beginning of our parameters, then we provide the parameter name and value. You can provide a list of parameters if you need to, you separate each parameter with an ampersand.
The response returns a JSON array of tweets. The content of a tweet is contained in the text
field. As you can see the latest Tweet from Spiderman is: “Learn how to draw Miles Morales, AKA Spider-Man, in this special Spanish-speaking lesson with artist @MikeHawthorne… https://t.co/RdvzWVzJ4o.”. 🕸️🎨
What is Spring and Spring Boot?
Spring is an open-source application framework. You can think of it a swiss-army knife for creating enterprise applications, it has different modules that provide a range of functions such as: authentication, data access, inversion of control, messaging, web services, and so on.
Spring’s philosophy is:
- Good design is more important than the underlying technology.
- Classes that are loosely coupled through interfaces is a good model.
- Code should be easy to test.
Spring follows convention-over-configuration. By following certain conventions such as naming things in a certain way, and implementing certain interfaces, it saves you writing a lot of repetitive code (boilerplate). It takes care of some of the cumbersome work for you, some things happen in the background magically!
Spring Boot makes life easier to create stand-alone, Spring-based applications. It is preconfigured with the Spring team’s “opinionated view” of the best configuration of the Spring platform and third-party libraries, so you can get started with minimum fuss. It has an embedded web server, so no need to manually deploy your application, you can just run your application.
What will we build?
We’ll build a web service for a User. We want someone to use our app, don’t we? 😅🙏
We will not use a database like a real application would. We will have some dummy data to mimic this.
The table below summarises our User API.
HTTP Method | Address | Action |
---|---|---|
GET | /users | Get all users |
GET | /users/{id} | Get users by id |
GET | /users?name=rob+oleary | Get user by name |
POST | /users | Add a new user |
PUT | /users | Update a user |
DELETE | /users/{id} | Delete a user |
When we run our App. The default local address for your Spring Boot application should be: http://localhost:8080
, so the address to get all users would be http://localhost:8080/users
for example.
Is this the “latest” way?
Spring is evolving version by version, so its worth noting that you may see some differences between examples, and this can be a bit confusing. Most choices are stylistic, and some are based on changes to the framework over time. The current stable version of Spring is 5.25, and 2.3.0 for Spring Boot.
If you use Spring Data Rest rather than the Spring Web starter dependency, you can do things differently. With Spring Data Rest, default controllers will be built by Spring for you, so if you are happy with the defaults in the convention, you do not have to define your own.
I would always suggest looking at the most recent tutorial that you can find, and choose a tutorial style that matches your learning preferences.
Is there anything I should know before I start?
A common issue when beginning to learn how to build APIs with Spring Boot is that tutorials expect you to know something about the design patterns that are being implicitly used by Spring; or they treat it as a mechanical process to follow: put this here, write a method like this, add this annotation, and on and on. This isn’t a great way to learn. I will help you to understand why you’re doing things in a particular way.
A little bit about Design Patterns
A design pattern is a general, reusable solution to a commonly occurring problem.
Design patterns can speed up the development process by providing tested, proven solutions. Reusing design patterns helps to prevent small mistakes that can cause major problems later on.
Bigger applications are divided into layers with particular responsibilities, this makes it easier to maintain
them. Spring uses the Model-View-Controller (MVC) design pattern for building web applications.
Model View Controller (MVC)
The big idea behind MVC is that each layer of your code has a specific purpose.
What is the purpose of each layer:
- Model: The Model captures the real-world things your application is concerned with. It models the real world. The classes in the model are used to store and manipulate the state of your application.
- View: The View is the user interface. It renders the model to the user. In a web application, this is the web pages we write in HTML. It is covers the “front-end” of your application. We don’t write this in our example application.
- Controller: The Controller layer is the liaison between the Model and the View layers, it receives the user input and decides what to do with it. A Controller in a web application has two parts. The first part is the web server that matches incoming HTTP Requests to a particular handler method, this is built-in part of Spring Boot. The second part is the handler methods themselves, which can be confusingly called “controllers” also, this is the bit that we write. The handler methods are responsible for returning data from the model.
The advantage of this approach is that our application is more loosely-coupled. You can change the view, but the model can remain the same. This separation of responsibility is what makes our application more maintainable.
If you would like a more in-depth explanation, you can read this MVC article.
Other patterns that are used in more advanced examples
In our example, we only use the MVC pattern implicitly.
In more advanced examples, you may also encounter or need to use the following design patterns:
- Data Access Object layer / Repository layer : When you use a database, you will probably use one of these patterns. This layer controls access to the stored data, it isolates other parts of the application from knowing about the source of the data, they don’t know if it is a database or spreadsheet or text file! Spring has a number of Spring Data libraries to support data repositories.
- Service layer: This layer is where our common business logic lives. A service uses repositories to perform tasks. For example, a Book Service might use the User repository and Book repository to offer functionality such as “search for my books”.
HTTP Basics
Hypertext Transfer Protocol (HTTP) is the foundation of data communication for the World Wide Web. It is a protocol that controls data transfer between a client application (such as a Web Browser) and a web server. Clients and servers communicate by exchanging individual messages. The messages sent by the client are called requests and the messages sent by the server in reply are called responses.
The target of an HTTP request is called a resource. Generally a web resource is a file on web server such as a document or a photo; but it has evolved to encompass any “thing” that is uniquely identifiable. Now it can encompass abstract resources such as classes and properties. Each resource is identified by a Uniform Resource Identifier (URI).
Uniform Resource Locator (URL)
The most common form of URI is the Uniform Resource Locator (URL), which is known as the web address. This is what you type into your Web Browser to load a page. A
A URL is composed of different parts, some are mandatory and others are optional.
- Scheme or protocol: It indicates which protocol must be used. Usually it is the HTTP or its secured version, HTTPS. This is required.
- Authority or domain name: This indicates the name of the Web Server being requested. Alternatively, it is possible to directly use an IP address, but because it is less convenient, it is not often used on the Web. This is required.
- Port: A port is a logical identifier to locate a specific process or service on the Web Server. It is usually omitted if the web server uses the standard ports of the HTTP protocol (80 for HTTP and 443 for HTTPS) to grant access to its resources. This is optional.
- Path: Is the path to the resource on the Web server. The path can represent a physical file location on the Web Server, or can be an abstraction handled by Web servers to find the resource.
- Query: It is a list of parameters. The parameters are a list of key-value pairs separated with an ampersand (
&
). The Web server can use the parameters to do some conditional logic. This is optional. - Fragment: It is an anchor to a part of the resource itself. An anchor is like a “bookmark” inside the resource, giving the browser the directions to show the content located at that spot. In an HTML document, for example, the browser will scroll to the point where the anchor is defined; for a video, the browser will try to go to the time the anchor represents. This is optional.
HTTP Request
A HTTP request consists of the following:
- a request line. For example,
GET http://localhost:8080/users/1 HTTP/1.1
, which wants to retrieve a resource identified by the path/users/1
from the server, - request header fields,
- an empty line,
- and an optional message body.
HTTP defines a set of request methods that define the action to be performed on a given resource. They are sometimes referred to a HTTP verbs. The following HTTP request methods are used in web applications:
- GET: Retrieve data of a resource.
- POST: Create a new resource.
- PUT: Update or replace a resource.
- PATCH: Update or modify a resource.
- DELETE: Delete a resource.
You will often see the core functions of a web application referred to as CRUD, which stands for: Create, Read, Update, Delete.
HTTP Response
The HTTP Response consists of the following:
- a status line which includes the status code and reason message,
- response header fields,
- an empty line,
- an optional message body.
Below is a summary of the typical content in a Response for the methods.
HTTP Method | CRUD | Response for an entire collection (e.g. /users) | Response for a specific item (e.g. /users/{id}) |
---|---|---|---|
POST | Create | Status Code: 201 (Created) if successful, 404 (Not Found) or 409 (Conflict) if the resource already exists. 'Location' header with link to /users/{id} where {id} is the new ID. |
Status Code: 201 (Created) if successful, 404 (Not Found) or 409 (Conflict) if the resource already exists. |
GET | Read | Status Code: 200 (OK). A list of users contained in the body. Pagination, sorting and filtering is used to enable navigation of big lists. |
Status Codes: 200 (OK) if successful, 404 (Not Found) if the ID is not found or invalid. Return the customer data in the body if it is successful. |
PUT | Update or Replace | Status Code: 405 (Method Not Allowed), unless you want to update/replace every resource in the entire collection. | Status Codes: 200 (OK) or 204 (No Content) if successful. 404 (Not Found), if the ID is not found or invalid. |
PATCH | Update or Modify | Status Code: 405 (Method Not Allowed), unless you want to modify the collection itself. | Status Codes: 200 (OK) or 204 (No Content) if successful. 404 (Not Found), if the ID not found or invalid. |
DELETE | Delete | Status Code: 405 (Method Not Allowed), unless you want to delete the whole collection, which is rarely desirable. | Status Codes: 200 (OK) if successful, 404 (Not Found), if the ID is not found or invalid. |
Further Reading on HTTP
For a more complete guide to HTTP, you can read Mozilla’s HTTP reference
A little bit about JSON
JSON stands for JavaScript Object Notation, and is a syntax for storing and exchanging data. JSON has become the favoured data format for web services, with XML being used less nowadays.
One of the reasons JSON is popular is that we can convert any JSON received from the server into JavaScript objects without any complicated parsing and translations, and since JavaScript is the language of the Web Browser, this makes building web applications simpler.
The syntax rules are simple:
- Data is in name-value pairs,
- Strings are contained in quotations,
- Data is separated by commas,
- Curly braces hold objects,
- Square brackets hold arrays.
For example, a user object would be written as:
An array of users would be written as:
Further Reading on JSON
This should be enough for you to know when dealing with web services, but for further information, W3schools has a short tutorial series on JSON.
A little bit about REST
You may have noticed I barely speak about REST in this article, and that’s because I think it is a term misused too often.
Representational state transfer (REST) is an architectural style that defines a set of constraints that can be followed when creating web services, which recommends using many of the conventions of the web. It was proposed by Roy Fielding in his doctoral dissertation in 2000.
I recommend reading this Stack Overflow thread on “What is Restful Programming” to understand more about it, and you can see some of the diversity of opinions on what a REST API is “in the wild”.
If you build web services with a framework like Spring Boot, you follow some of the conventions of restful API design by default, but some would consider it a HTTP-based web service, rather than a restful web service. It gets murky quickly when people talk about how restful a web application is by comparing it to the academic definition, I don’t think it is a productive endeavour to do so.
One of the constraints of REST is to use Hypermedia as the Engine of Application State (HATEOS), which can be done in Spring Boot if you use the Spring Data Rest starter dependency. In practice, most APIs do not follow this constraint, and this leads some people to say, “well, it is not a rest API then”. 😅 There is merit in following this constraint, but for a clients to use HATEOAS properly takes more work, and I guess that’s why people tend to avoid it.
For me, the key part is to be pragmatic when making web services, make them intuitive to use, and easy to extend. What most people tend to agree on, and follow, is to arrange an application into resources, we do this in our Model, and leverage HTTP methods to implement functionality on a resource. The convention is to use an uniform path for a resource such as /users
, which is the pluralized version of the name of the resource. This is an exceptional post about pragmatic restful API design, if you want to understand the conventions well.
What are the prerequisites for completing this tutorial?
Some time and software!
You need:
- About 1 hour,
- Your favourite text editor or IDE,
- JDK 1.8 or later installed,
- Gradle or Maven. You can skip this depending on your IDE, for example IntelliJ has maven built-in. I use maven.
How to create a new Spring project
You can use Spring Initializr to create your project. It offers a fast way to create a skeleton project.
Only one dependency is required for this project and that is Spring Web.
To use Spring Initializr, fill in fields, and click generate. You can then download your project in a zip file.
Unzip the file and open it in your IDE of choice.
The dependencies may be downloaded automatically by your IDE when you import/open the project, or you may need to trigger the download yourself:
- In IntelliJ, you can go to
File > Synchronise
in the menu to trigger the download. - On the command-line:
- For maven, run the command
mvn install
. - For gradle, run the command
gradle build
.
- For maven, run the command
Spring Initializr creates a default class to run you web application called UserApplication.java. You can run this to verify you are set-up correctly. It will run a web server for you, nothing more than that because we have written any code yet! You should see something like this on the command-line if it is set-up correctly:
You can follow along and write the code with me, or you can download the complete code from github.
Write the code
Get All Users
Let’s begin by writing the code to get all of our users.
Create a model class
Our application is all about the user, which every application should be! 😉
We want to create a User
class that has the attributes: id, name, and age.
Behind the scenes, Spring may need to create empty objects when creating or updating users (responding to POST and PUT requests). So, you always need to include a no-args constructor if you want to support these actions.
We add the typical methods to make a regular java class. Setter and getters are required for retrieving and modifying the attributes. We must include equals
and hashCode
methods to support the comparison of User objects. I used IntelliJ to generate all of these methods.
Create a controller class
Remember, the controller is responsible for matching the HTTP request with a java method that returns a response.
We add annotations to our Controller to implement functionality. @RestController
marks the class as a Rest Controller, so Spring can link some functionality. We specify that the Controller should interpet all requests for the path /users
with @RequestMapping ("/users")
.
We add methods to handle different requests and annotate them to indicate the HTTP method they are responding to. We return data from the method and Spring is going to transform the data into JSON for us and return it in a response.
I have created an ArrayList
of users to have some data to return.
The getUsers
method (you can call it whatever you want) returns all of the users for the URL http://localhost:8080/users. We tie the URL with our method using an annotation of @RequestMapping
or @GetMapping
. We return the ArrayList
from our method.
@RequestMapping
Variants
Spring 4.3 introduced shortcut annotations, which serve the same purpose as @RequestMapping
but have the HTTP method as part it’s name.
You may seen them used also. They are:
@GetMapping
@PostMapping
@PutMapping
@DeleteMapping
@PatchMapping
So, to annotate your method you could use this:
or this:
Create a class to start the application
If you used Spring Initialzr, then this class is already created for you!
This is the main class which initiates the packaging of your web application, and then starts an embedded web server to run our web service for us.
That’s the hard bit done!
Now, does it work?
Run the UserApplication
class, you can test the GET
method in your Web Browser.
Get user by ID
To get the user by ID, we want to be able to specify the ID in the URL.
For example, we navigate to http://localhost:8080/users/2 to get the user with an ID of 2, and we expect to get this response:
We put the variable name within curly brackets as part of our @GetMapping
annotation, and we declare it using the @PathVariable
annotation in our method signature. We search through our ArrayList
to find the first user with that id.
If an user is found, we return an OK status (200). If the user is not found, we return a Not Found Status (404).
Get user by name
To get the user by name, we want to be able to specify a parameter at the end of the URL.
For example, we navigate to [http://localhost:8080/users?name=rob oleary](http://localhost:8080/users?name=rob oleary)
to get the user with a name of “rob oleary”.
A browser may add “+” for the space in the address like this: http://localhost:8080/user?name=rob+oleary,
spaces in URLs are considered unsafe. You don’t need to do anything differently, it will work either way! We expect to get this response:
We need to add params
to our @GetMapping
annotation to specify the parameter name. We need this to define an unique path, so Spring can map the request to the correct method with certainty.
We specify @RequestParam
in our method signature, so we can use this variable inside our method to search for the user with that name. We use equalsIgnoreCase()
to accept whatever mix of big and small letters we get from the client.
We return a status depending on if the user was found or not.
Add a new user
We add the user to our ArrayList
. We use ResponseEntity
as our method return type, it is a wrapper class where we can optionally include things such as: the status code (outcome of action), and headers to give the client information about the outcome.
This time our parameter is annotated with @RequestBody
, this is because the data is provided in the body of the HTTP Request.
We return a status code of HttpStatus.CREATED, which is HTTP code of 201. There is no opportunity for there to be a failure to add a new user to our ArrayList
, but you should consider this if you use a database.
Update a user
Updates a user, or add a new user if there is no user found.
A PUT method is idempotent, which means if you run the operation multiple times, the result is the same.
Our parameter is annotated with @RequestBody
again.
We return different status codes depending on whether we updated or added a user.
We don’t use PATCH in our web application. PATCH is used for partial update.
This may be used when you use a database as it is more efficient to only update specifically what has changed, rather than replacing an entire object. As we are doing everything in memory with an ArrayList
, there is no benefit to this.
Delete a user
We remove the user from our ArrayList
, and return a status code to indicate if the user was found or not.
How to test your application
If you want to create automated tests for your code, this is a separate topic that deserves more time.
For now, as a sanity check, you can execute GET methods in your browser. You can use a client application like Insomonia to execute other methods.
Here is a quick example to add a new user using Insomonia. We make a POST request like below, we put a JSON object of our new user in the request body, and set the body type to JSON (this usually sets the Content-Type header to “application/json”). A status code of 201 indicates the user was created successfully.
Source code
You can download the complete code from github.
Next steps
- Read the next article to learn how to test the API.
- Add a database to store your data long-term.
- Build a complete API of something you are interested in.
- Learn how to add authentication to control access to data.
- Learn how to document your API. You can use libraries such as AsciiDoctor and Swagger to largely automate this.
Let me know if you are interested in a follow-up article regarding one of the topics above! 🙂
Happy coding! 👩💻🙌
Icons for diagrams are from the Noun Project: Mobile by Rainbow Designs, Cloud by James Kopina, Database by Kimmi Studios, User by Adrian Coquet, Twitter by Acid Beast.