Guide: Building a Simple REST API with
Spring Boot
This document provides a step-by-step guide to creating your first REST API using Spring
Boot. This is a common way to build backend services that can be used by web and mobile
applications.
1. What is a REST API?
A REST API (Representational State Transfer Application Programming Interface) is a set of
rules that developers follow when they create an API. Think of it as a contract between a client
(like a web browser or mobile app) and a server. The client sends a request to the server, and
the server sends back a response, usually in a data format like JSON.
Common Operations (HTTP Methods):
● GET: Retrieve data from the server.
● POST: Send new data to the server to create something.
● PUT: Update existing data on the server.
● DELETE: Remove data from the server.
2. Setting Up Your Spring Boot Project
The easiest way to start is with the Spring Initializr. This is a web tool that generates a basic
project structure for you.
1. Go to start.spring.io.
2. Choose the following settings:
○ Project: Maven
○ Language: Java
○ Spring Boot: The latest stable version (e.g., 3.x.x)
○ Project Metadata:
■ Group: com.example
■ Artifact: demo-api
■ Name: demo-api
■ Packaging: Jar
■ Java: 17 (or a recent LTS version)
3. In the Dependencies section, click "Add Dependencies" and add:
○ Spring Web: This is essential for building web applications and REST APIs.
4. Click Generate. A .zip file will be downloaded. Unzip it and open the folder in your
favorite IDE (like IntelliJ IDEA or VS Code).
3. Creating the "Model" (The Data Structure)
A model is a simple Java class that defines the structure of the data you want to work with.
Let's create an API for managing a list of Book objects.
Step 1: Create the Book class
Inside your project, navigate to src/main/java/com/example/demoapi and create a new file
named Book.java.
Code Example (Book.java):
package com.example.demoapi;
public class Book {
private long id;
private String title;
private String author;
// Constructor
public Book(long id, String title, String author) {
this.id = id;
this.title = title;
this.author = author;
}
// Getters and Setters
public long getId() {
return id;
}
public void setId(long id) {
this.id = id;
}
public String getTitle() {
return title;
}
public void setTitle(String title) {
this.title = title;
}
public String getAuthor() {
return author;
}
public void setAuthor(String author) {
this.author = author;
}
}
How the Code Works
● This is a standard Java class (a "POJO" - Plain Old Java Object).
● It has three private fields (id, title, author) to hold the data for a single book.
● The constructor is a special method used to create a new Book object with initial values.
● Getters and Setters are public methods that allow other parts of the code to safely
access and modify the private fields. Spring Boot uses these to automatically convert the
object to and from JSON.
4. Creating the "Controller" (The API Endpoints)
A controller is the part of your code that handles incoming web requests and sends back
responses. It defines the URLs (or "endpoints") for your API.
Step 1: Create the BookController class
In the same directory, create a new file named BookController.java.
Code Example (BookController.java):
package com.example.demoapi;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.ArrayList;
import java.util.List;
@RestController
public class BookController {
@GetMapping("/books")
public List<Book> getAllBooks() {
List<Book> books = new ArrayList<>();
books.add(new Book(1, "Clean Code", "Robert C. Martin"));
books.add(new Book(2, "The Pragmatic Programmer", "Andrew Hunt"));
return books;
}
}
How the Code Works
● @RestController: This annotation tells Spring that this class is a controller designed to
handle REST API requests. It automatically handles converting data to JSON.
● @GetMapping("/books"): This annotation maps HTTP GET requests for the URL /books
to the getAllBooks() method. When someone visits http://localhost:8080/books, this
method will be executed.
● public List<Book> getAllBooks(): This method creates a simple list of Book objects.
● return books;: Spring Boot is smart. When it sees you are returning a List<Book> from a
@RestController, it automatically converts that list into JSON format for the response.
5. Running the Application
The main application file was created for you by the Spring Initializr.
Step 1: Find and run the main class
Navigate to DemoApiApplication.java in your main project folder. This class will have a main
method.
package com.example.demoapi;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class DemoApiApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApiApplication.class, args);
}
}
Step 2: Run the code
Right-click on this file in your IDE and select "Run". Your Spring Boot application will start.
You'll see a lot of logs in your console, ending with a message indicating it has started.
Step 3: Test the API
Open a web browser or an API testing tool like Postman and go to the following URL:
http://localhost:8080/books
You should see the following JSON response:
[
{
"id": 1,
"title": "Clean Code",
"author": "Robert C. Martin"
},
{
"id": 2,
"title": "The Pragmatic Programmer",
"author": "Andrew Hunt"
}
]
Congratulations, you've just built and tested your first REST API with Spring Boot!
