In this tutorial you will build a REST API using Spring Boot. We will cover controllers, services, repositories and validation.
Use start.spring.io to bootstrap a project with the Web and JPA dependencies.
Create a JPA entity annotated with @Entity.
Add a @RestController and map CRUD endpoints.
If you are learning Java and keep hearing the name Spring Boot, this tutorial is for you. We will explain what Spring Boot is, the problem it was built to solve, and why it has become the default way to build Java applications. No prior Spring knowledge is assumed. By the end you will understand what the framework does for you and be ready to build your first app.
Spring Boot is a framework that helps you build Java applications, especially web applications and services, quickly and with very little setup. It takes care of the tedious configuration that used to consume the first hours of every project, so you can start writing the parts that matter almost immediately.
If that sounds vague, do not worry. The value of Spring Boot is easiest to understand once you know what came before it.
Spring Boot is built on top of the older Spring framework. Spring is powerful and has been popular for a long time, but it earned a reputation for being hard to set up. To build even a small web application, a developer had to configure many pieces by hand: the web server, the way requests were routed, the database connection, and a great deal of wiring to tell the framework how the parts fit together. Much of this configuration lived in long XML files that were easy to get wrong.
The result was that starting a new project was slow and error-prone. Developers spent their first day fighting configuration instead of building features. Spring Boot was created to fix exactly this. Its guiding idea is convention over configuration: instead of asking you to specify everything, it makes sensible default choices and lets you override them only when you need something different.
Four features do most of the work. Understanding them is understanding Spring Boot.
When your app starts, Spring Boot looks at which libraries are present and configures them with reasonable defaults. If it sees a database library, it sets up a database connection. If it sees the web library, it sets up a web server. You get working behaviour without writing configuration, and you can override any default when your needs differ.
Adding a feature to a Java project traditionally meant hunting down several libraries and making sure their versions were compatible. Spring Boot bundles these into starters. Adding spring-boot-starter-web, for example, pulls in everything needed to build a web application, already tested to work together. One line replaces a dozen.
Older Java web apps had to be packaged and deployed into a separate web server that you installed and managed. Spring Boot includes the server inside your application. You run your app like any normal program and it serves web requests on its own. This makes running and deploying dramatically simpler.
Spring Boot includes tools for running an app in the real world, such as health checks that report whether the app is working and metrics that show how it is performing. These are the unglamorous things every serious application needs, available without extra effort.
Talk is cheap, so here is an entire working web application. This is not a fragment; it is the whole thing:
@SpringBootApplication
@RestController
public class HelloApp {
public static void main(String[] args) {
SpringApplication.run(HelloApp.class, args);
}
@GetMapping("/")
public String hello() {
return "Hello from Spring Boot!";
}
}Run that main method and open http://localhost:8080 in your browser. You will see the greeting. Consider what you did not have to do: you did not install a web server, write any configuration files, or specify a port. Spring Boot made those choices and started everything for you. That is the convenience the framework is famous for.
The @SpringBootApplication annotation is the on-switch that turns on auto-configuration and tells Spring to scan your code for parts to manage. The @RestController and @GetMapping annotations set up a single web endpoint. We cover these in their own tutorials; for now, just notice how little code stands between you and a running web app.
A common worry for beginners is whether Spring Boot replaces Java or hides it. It does neither. Everything you write is ordinary Java: classes, methods, and objects. Spring Boot is a set of libraries you use from your Java code. The skills you build learning core Java, such as classes, collections and exceptions, apply directly. Spring Boot simply handles the plumbing around your code so you can focus on logic.
Spring Boot is an excellent default for a wide range of projects:
It is less suited to tiny throwaway scripts, where its startup and structure are more than you need, and it is not used for front-end code that runs in the browser, which is the job of JavaScript. But for building the server side of a Java application, it is hard to beat.
Now that you know what Spring Boot is, a sensible order to learn it is: set up your first project, understand the main annotation that starts everything, build a simple web endpoint, then connect to a database so your app can remember data. Each of these has its own tutorial, and they build on one another. Take them in order and you will have a solid foundation.
The most important thing to take away is the philosophy. Spring Boot trusts sensible defaults and asks you to configure only what is special about your app. Keep that in mind and the framework will feel less like magic and more like a helpful assistant that has already done the boring parts for you.
Getting a Spring Boot project running for the first time can feel intimidating if you have never used a build tool before, but the whole process takes only a few minutes once you know the steps. This tutorial walks through creating a project with Spring Initializr, understanding what gets generated, and running it successfully, including the small mistakes that trip up most beginners.
Go to start.spring.io in a browser. This is an official tool from the Spring team that generates a ready-to-open project based on a few choices, so there is nothing to install before you even begin.
Click Generate. A zip file downloads containing the full project structure. Unzip it and open the folder in an editor built for Java, such as IntelliJ IDEA or VS Code with the Java extensions installed. The editor will usually recognise the pom.xml file and offer to download the required libraries automatically.
A few files matter most at this stage. The pom.xml file lists every dependency the project needs and tells Maven how to build it; this is what changes when a new starter is added later. Inside src/main/java sits a single class ending in Application, marked with @SpringBootApplication, which is the entry point of the whole program. Inside src/main/resources sits application.properties, an initially empty file used for configuration, and a templates folder if a view engine like Thymeleaf was included.
Find the Application class and run its main method, either through the editor's run button or from a terminal:
mvn spring-boot:runWatch the console output. A successful start ends with a line mentioning Tomcat started on port 8080. Opening http://localhost:8080 in a browser will show a generic error page at this point, which is expected, since no endpoint has been created yet; it confirms the server itself is running correctly.
With a running project in place, the natural next step is understanding the @SpringBootApplication annotation that made the whole thing work, followed by building a first REST endpoint so the app actually responds with something meaningful.
Every Spring Boot application has exactly one class marked with @SpringBootApplication, usually the one containing the main method. It looks like a single simple annotation, but it is actually doing three separate jobs at once, and understanding each of them removes a lot of the mystery around how a Spring Boot app starts.
Placing @SpringBootApplication on a class has exactly the same effect as stacking these three annotations together:
@SpringBootApplication
public class MyApp {
public static void main(String[] args) {
SpringApplication.run(MyApp.class, args);
}
}The run method does the real work: it creates the Spring application context, triggers component scanning and auto-configuration, and starts the embedded server if a web starter is present. Everything else in the application builds on top of the context this single line creates.
Because @ComponentScan only looks in the current package and its sub-packages, the class carrying @SpringBootApplication should sit at the top level of the project's package structure, for example com.example.demo, with controllers, services and repositories organised in packages beneath it. A class placed in a sibling package that component scanning cannot reach will simply be invisible to Spring, which is one of the most common causes of a confusing missing-bean error for beginners.
Auto-configuration makes sensible guesses, but it always steps aside if a bean of the same type is defined explicitly. For example, if a custom DataSource bean is declared, Spring Boot's automatic database configuration backs off and uses that one instead. This override-friendly design is what makes auto-configuration safe to rely on: it saves effort in the common case without locking a project into defaults it cannot escape.
This class is rarely edited after it is created. What matters is knowing that its single annotation is responsible for turning on scanning, auto-configuration and the ability to define beans, which together explain why a Spring Boot application can do so much while the developer writes comparatively little code.
A REST API is how one program talks to another over the web. When a mobile app loads your profile, or a website shows a list of products, there is almost always a REST API behind it, quietly handing over data. In this tutorial you will build one from scratch with Spring Boot, understand every line, and learn the patterns you will reuse in almost every project. We will go slowly and explain the why, not just the how.
REST is a set of ideas for building web services. The core idea is simple: you have resources, such as users or products, and you act on them using standard web requests. Each resource has an address, called a URL, and you use different request types to read, create, update or delete it. You do not need to memorise the theory to get started; you mostly need to know four request types and what each is for.
These four map neatly onto the things most apps need to do with their data. People often call this pattern CRUD, short for Create, Read, Update and Delete.
Before writing an endpoint, you need a Spring Boot project with the web tools included. The quickest way is Spring Initializr at start.spring.io. Choose Maven, Java, and add the Spring Web dependency. Generate the project, unzip it, and open it in your editor. If you have followed the earlier setup tutorial, you already have everything you need.
The important dependency is spring-boot-starter-web. It brings in the web server and the tools that turn your Java objects into JSON automatically. You do not configure any of it; adding the starter is enough.
Let us start with the smallest possible working endpoint, then grow it. Create a new class called ProductController:
@RestController
@RequestMapping("/products")
public class ProductController {
@GetMapping
public String list() {
return "This will list products";
}
}Run the app and open http://localhost:8080/products in your browser. You will see the text. Let us unpack the three annotations, because you will use them constantly.
This tells Spring two things: the class handles web requests, and whatever its methods return should be sent straight back to the caller as the response body. Without the Rest part, Spring would think the returned text was the name of a web page to display.
This sets a base path for every method in the class. Because we put it on the class, every endpoint inside starts with /products. It saves you from repeating the path on each method and keeps related endpoints grouped.
This marks the method as the handler for GET requests to the base path. Since the class path is /products and there is nothing extra here, this method answers GET /products.
An API that returns a sentence is not very useful. Real APIs return structured data. In Java you model that data as a class. Create a simple Product class:
public class Product {
private Long id;
private String name;
private double price;
public Product(Long id, String name, double price) {
this.id = id;
this.name = name;
this.price = price;
}
// getters and setters
}Now change the controller to return a list of products. To keep this tutorial focused on the API itself, we will store the products in memory rather than a database:
@RestController
@RequestMapping("/products")
public class ProductController {
private final List products = new ArrayList<>(List.of(
new Product(1L, "Notebook", 4.50),
new Product(2L, "Pen", 1.20)
));
@GetMapping
public List list() {
return products;
}
} Restart and open /products again. This time you will see JSON, something like this:
[
{ "id": 1, "name": "Notebook", "price": 4.5 },
{ "id": 2, "name": "Pen", "price": 1.2 }
]You did not write any code to build that JSON. Spring Boot saw that your method returns a list of objects and converted it for you. This automatic conversion is one of the biggest conveniences of the framework.
Listing everything is common, but so is fetching one item by its id. The id belongs in the URL path, like /products/1. You capture it with a path variable:
@GetMapping("/{id}")
public Product getOne(@PathVariable Long id) {
return products.stream()
.filter(p -> p.getId().equals(id))
.findFirst()
.orElse(null);
}The {id} in the path is a placeholder. The @PathVariable annotation tells Spring to take that part of the URL and pass it into your method. Now GET /products/1 returns just the notebook. We will improve the not-found case shortly.
To add a new product, the caller sends its details in the request body as JSON. You receive it with @RequestBody:
@PostMapping
public Product create(@RequestBody Product product) {
products.add(product);
return product;
}The @RequestBody annotation is the mirror image of returning an object. Spring reads the incoming JSON and builds a Product object from it. You then store it and return it, often so the caller can see the final saved version, including any id the server assigned.
You cannot test POST by typing a URL in the browser, because browsers only send GET that way. Use a tool such as Postman, or the curl command in your terminal:
curl -X POST http://localhost:8080/products
-H "Content-Type: application/json"
-d '{"id":3,"name":"Eraser","price":0.9}'Updating uses PUT and usually combines a path variable, to say which item, with a request body, to carry the new values:
@PutMapping("/{id}")
public Product update(@PathVariable Long id,
@RequestBody Product updated) {
// find the product and replace its values
return updated;
}Deleting uses DELETE and only needs to know which item to remove:
@DeleteMapping("/{id}")
public void delete(@PathVariable Long id) {
products.removeIf(p -> p.getId().equals(id));
}With these four request types in place, your API can now create, read, update and delete products. That is a complete CRUD API.
Every web response carries a status code, a number that tells the caller what happened. You have probably seen 404, which means not found. A good API uses these codes correctly so callers can react. Returning an object directly always gives 200, which means success, even when the item was missing. To control the code, wrap your result in ResponseEntity:
@GetMapping("/{id}")
public ResponseEntity getOne(@PathVariable Long id) {
return products.stream()
.filter(p -> p.getId().equals(id))
.findFirst()
.map(ResponseEntity::ok) // 200 with the product
.orElse(ResponseEntity.notFound().build()); // 404
} Now a missing product returns 404 instead of an empty 200 response. Here are the status codes you will use most:
As your API grows, a handful of habits keep it clean and predictable:
You now have a working REST API and understand what each part does. The natural next step is to store your data in a real database instead of an in-memory list, so it survives restarts. The tutorial on connecting Spring Boot to a database with JPA picks up exactly where this one leaves off. After that, adding validation and centralised error handling will take your API from working to production-ready.
The pattern you learned here, a controller with GET, POST, PUT and DELETE methods over a resource, is the backbone of most Spring Boot services you will ever build. Once it feels natural, the rest of the framework becomes much easier to learn.
Almost every real endpoint needs some input from the caller, and the URL itself is one of the most common places to carry it. Spring Boot gives two complementary tools for this: path variables, which are part of the URL structure, and query parameters, which are optional extras appended after a question mark. Knowing which one fits a given situation makes an API much easier to use correctly.
A path variable identifies a specific resource and is embedded directly in the URL path, such as the 5 in /users/5. It is captured with @PathVariable:
@GetMapping("/users/{id}")
public String find(@PathVariable Long id) {
return "You asked for user " + id;
}Spring automatically converts the text from the URL into the declared type, so a request to /users/5 arrives as the Long value 5 rather than the text "5". If the value cannot be converted, for example letters where a number is expected, Spring responds with a 400 Bad Request automatically, without any extra code.
A path can carry more than one variable when a resource is nested inside another, such as a comment belonging to a specific post:
@GetMapping("/posts/{postId}/comments/{commentId}")
public String getComment(@PathVariable Long postId,
@PathVariable Long commentId) {
return "Post " + postId + ", comment " + commentId;
}A query parameter comes after a question mark in the URL, like /search?term=java, and is meant for optional extras rather than identifying a resource, such as filters, sorting or pagination. It is captured with @RequestParam:
@GetMapping("/search")
public String search(@RequestParam String term) {
return "Searching for " + term;
}By default, @RequestParam requires the parameter to be present, and a missing one causes an error. A default value avoids this and makes the parameter genuinely optional:
@GetMapping("/products")
public String list(@RequestParam(defaultValue = "0") int page,
@RequestParam(required = false) String category) {
return "page=" + page + ", category=" + category;
}Following this distinction consistently makes an API predictable: anyone reading a URL can tell at a glance whether a value names a specific thing or simply adjusts how the results are returned, which matters more as an API grows past a handful of endpoints.
Whenever a client creates or updates data, it typically sends the details as a JSON document in the body of the request rather than in the URL. Spring Boot can turn that JSON straight into a Java object automatically, using a library called Jackson behind the scenes, so the incoming data can be worked with as ordinary objects rather than raw text.
public class Product {
private String name;
private double price;
// getters and setters
}Jackson matches JSON fields to Java fields by name, using the getters and setters to read and write values, which is why a class intended to receive JSON needs both, even though a plain object elsewhere in the code might not.
The @RequestBody annotation tells Spring to read the JSON from the incoming request and build an object from it before the method even runs:
@PostMapping("/products")
public Product create(@RequestBody Product product) {
// save product here
return product;
}{ "name": "Book", "price": 9.99 }Spring reads this JSON and creates a Product object with those values already filled in, with no manual parsing required anywhere in the method.
@RequestBody is not limited to flat objects. If a Product had a nested Category object, or the endpoint accepted a list of products, Jackson handles both automatically, as long as the Java classes mirror the structure of the JSON:
@PostMapping("/products/bulk")
public List<Product> createMany(@RequestBody List<Product> products) {
return products;
}curl -X POST http://localhost:8080/products
-H "Content-Type: application/json"
-d '{"name":"Book","price":9.99}'With @RequestBody in place, an API can accept structured input just as easily as it returns structured output, which is the second half of building a complete, working REST endpoint.
Almost every real application needs to remember things between restarts: users, orders, posts, settings. That is what a database is for. In this tutorial you will connect a Spring Boot app to a database and read and write data using Spring Data JPA. The goal is that by the end you can store Java objects and get them back without writing SQL by hand, and you understand what is happening under the surface.
Two names come up together and it helps to separate them. JPA, the Java Persistence API, is a standard way to map Java objects to database tables. It lets you treat rows in a table as ordinary Java objects. Spring Data JPA is a Spring library that sits on top of JPA and removes most of the repetitive code, giving you ready-made ways to save and query data. You will mostly interact with Spring Data JPA, and it uses JPA underneath.
The mental model is simple. A Java class becomes a table. An object of that class becomes a row. A field becomes a column. Once that mapping is set up, saving an object writes a row, and loading a row gives you back an object.
You need two things: the Spring Data JPA starter, and a database driver. For learning, an in-memory database called H2 is perfect because it needs no installation and resets each time you run the app. In your project, include:
With H2 on the classpath, Spring Boot automatically configures a database connection for you. You do not have to write connection code. For a real deployment you would swap H2 for something like PostgreSQL and provide connection details, but the rest of your code stays the same.
An entity is a Java class that maps to a table. You mark it with @Entity, and you mark one field as the primary key with @Id. Here is a Book entity:
@Entity
public class Book {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private String title;
private String author;
protected Book() { } // required by JPA
public Book(String title, String author) {
this.title = title;
this.author = author;
}
// getters and setters
}A few details matter here. The @Id marks the primary key, the unique identifier for each row. The @GeneratedValue with IDENTITY tells the database to assign the id automatically as rows are inserted, so you never set it yourself. JPA also requires a no-argument constructor, which is why there is an empty protected one; it is used internally when JPA rebuilds objects from rows.
You do not need to write a CREATE TABLE statement. In development, Spring Boot can create the table from your entity automatically. In production you would manage the schema with a migration tool, but for now the automatic creation lets you move fast.
This is where Spring Data JPA saves you the most work. Instead of writing methods to save and fetch books, you declare an interface that extends JpaRepository, and Spring provides the implementation at runtime:
public interface BookRepository
extends JpaRepository {
} The two types in the angle brackets say: this repository manages Book entities, whose id is of type Long. That single empty interface gives you a surprising number of methods for free:
You never write the bodies of these methods. Spring builds them for you when the app starts. This is the heart of Spring Data: you describe what you want, and it supplies the how.
To use the repository, you ask Spring to give you one. The clean way is constructor injection, where you accept the repository as a constructor parameter and Spring passes it in:
@Service
public class BookService {
private final BookRepository repo;
public BookService(BookRepository repo) {
this.repo = repo;
}
public Book add(String title, String author) {
return repo.save(new Book(title, author));
}
public List all() {
return repo.findAll();
}
} When you call save, Spring Data writes a row and, because the id is generated, fills in the new id on the returned object. When you call findAll, it reads every row and turns each into a Book object. No SQL appears anywhere in your code.
Sooner or later you need to find data by something other than the id, for example all books by a certain author. Spring Data has a clever feature: it can build a query from the method name. You simply declare the method in your repository interface:
public interface BookRepository
extends JpaRepository {
List findByAuthor(String author);
List findByTitleContaining(String text);
} Spring reads the method name and works out the query. findByAuthor searches the author column for an exact match. findByTitleContaining searches for titles that include the given text, useful for a search box. You wrote no query at all; the name was enough.
This works for many patterns: findBy, combined with And and Or, with OrderBy for sorting, and with keywords like GreaterThan or Between for ranges. When a name would get too complicated, you can fall back to writing a query yourself with the @Query annotation, but you will be surprised how far the naming approach takes you.
A transaction is a group of database operations that must all succeed together or not at all. Imagine transferring money: you subtract from one account and add to another. If the second step fails, you must undo the first, or money vanishes. Spring manages this for you with the @Transactional annotation:
@Service
public class TransferService {
@Transactional
public void transfer(Long from, Long to, double amount) {
// withdraw from one, deposit to the other
// if anything throws, both are rolled back
}
}If the method finishes normally, all changes are saved together. If it throws an exception, Spring rolls everything back, leaving the database as it was. For simple single saves you rarely need to think about this, but for multi-step operations it prevents half-finished states.
As your data grows, one performance trap catches almost everyone. Suppose each book has a list of reviews, and you load all books and then loop through printing each book's reviews. Without care, the app runs one query to load the books, then one extra query per book to load its reviews. With a hundred books that is a hundred and one queries, and the page crawls.
The fix is to tell JPA to load the related data in one go, using a fetch join or an entity graph. You do not need the details yet, but it helps to know the name of the problem. If a page that loads a list is mysteriously slow, the N plus one problem is the first thing to check.
You now have the full loop: an entity that maps to a table, a repository that gives you save and query methods for free, and a service that uses them. Combine this with the REST API tutorial and you can build an endpoint that stores real data:
@RestController
@RequestMapping("/books")
public class BookController {
private final BookRepository repo;
public BookController(BookRepository repo) {
this.repo = repo;
}
@GetMapping
public List all() { return repo.findAll(); }
@PostMapping
public Book add(@RequestBody Book book) {
return repo.save(book);
}
} Now a POST to /books saves a book to the database, and a GET returns everything stored. Restart the app with a real database and the data is still there.
From here, three steps will round out your database skills. First, move from H2 to a real database like PostgreSQL by changing only the configuration. Second, add validation so bad data never reaches the database. Third, learn about relationships, such as an author having many books, which JPA models with annotations like @OneToMany. Each builds on the foundation you have here: objects in, rows out, with Spring Data doing the heavy lifting.
REST APIs return raw data, but many applications also need to serve complete web pages that a browser can display directly. Thymeleaf is a template engine bundled with Spring Boot that builds HTML pages by combining a template file with data supplied from a controller, without needing a separate front-end framework.
Including spring-boot-starter-thymeleaf in the project is enough to enable it. Once present, Spring Boot automatically looks for template files inside src/main/resources/templates and serves them when a controller returns a matching name.
A page-rendering controller uses @Controller rather than @RestController, because its methods should return the name of a template rather than raw data. Values are passed to the template through a Model object:
@Controller
public class HomeController {
@GetMapping("/")
public String home(Model model) {
model.addAttribute("name", "World");
return "home";
}
}Create home.html inside the templates folder. Thymeleaf attributes, all prefixed with th:, fill placeholders with real data when the page is rendered:
<h1 th:text="'Hello ' + ${name}">Hello</h1>The th:text attribute replaces the tag's normal content with the given expression once rendered, so a browser viewing the page sees "Hello World" instead of the placeholder text "Hello" that appears only if the file is opened directly without Thymeleaf processing it.
Two attributes cover most everyday templating needs. th:if only renders an element when a condition is true:
<p th:if="${user != null}">Welcome back!</p>th:each repeats an element once per item in a collection:
<li th:each="item : ${items}" th:text="${item}"></li>Thymeleaf provides a special link syntax, @{...}, that correctly builds application-relative URLs for stylesheets, scripts and links, which matters once the app is deployed somewhere other than localhost:
<link th:href="@{/css/site.css}" rel="stylesheet">
<a th:href="@{/products}">See products</a>It is worth being clear about when to reach for Thymeleaf rather than a REST endpoint. A REST API, built with @RestController, suits a mobile app or a separate JavaScript front end that wants raw data. Thymeleaf suits an application where the server itself produces the finished HTML that a browser displays, which remains a simple and effective choice for content-focused sites, admin panels and traditional multi-page web applications.
Almost every application needs settings that differ between environments: a different database on a laptop than in production, a different port during testing, or a secret key that should never be written directly into code. Spring Boot reads these kinds of settings from application.properties, letting behaviour change without touching a single line of Java.
The file sits in src/main/resources and is read automatically the moment the application starts. Spring Boot itself already understands a long list of built-in settings, and a project can also define its own for its specific needs, all in the same simple key equals value format:
server.port=9090
spring.datasource.url=jdbc:h2:mem:test
spring.jpa.hibernate.ddl-auto=update
app.welcome-message=Welcome to my siteThe first line changes the port the app listens on. The next two configure the database connection and how Hibernate manages the schema. The last is a custom property that only this application understands, since it does not match any setting Spring Boot recognises on its own.
The @Value annotation injects a single property straight into a field:
@Value("${app.welcome-message}")
private String welcome;Once a feature has several related settings, @ConfigurationProperties is usually cleaner than several separate @Value fields. It binds a whole group of properties sharing a prefix onto one class:
@ConfigurationProperties(prefix = "app.mail")
public class MailProperties {
private String host;
private int port;
// getters and setters
}app.mail.host=smtp.example.com
app.mail.port=587This keeps configuration organised as a project grows, since related settings live together on one typed class instead of scattered across many separate injected fields.
Spring Boot supports profile-specific files, such as application-dev.properties and application-prod.properties, which override or add to the base file when that profile is active. Activating a profile is as simple as setting spring.profiles.active=dev, letting a database point at a local instance during development and a real server in production, without changing any code between the two.
A password or API key should not be committed to source control inside application.properties. Spring Boot allows any property to be overridden by an environment variable, so a value like spring.datasource.password can instead be supplied as SPRING_DATASOURCE_PASSWORD on the machine running the application, keeping secrets outside the codebase entirely while the code stays unaware of the difference.
Centralising configuration this way means the same compiled application can behave differently depending only on which properties file or environment variables are present when it starts, which is exactly the flexibility needed to move an application from a laptop to a test server to production without rebuilding it each time.
An API that fails silently, or worse, sends back a raw stack trace, is difficult and frustrating to work with. A well-designed API tells the caller exactly what went wrong, using a clear message and the correct HTTP status code, so client applications can react sensibly instead of guessing.
Wrapping a result in ResponseEntity gives full control over the status code returned, rather than always defaulting to 200:
@GetMapping("/items/{id}")
public ResponseEntity<Item> get(@PathVariable Long id) {
return repo.findById(id)
.map(ResponseEntity::ok)
.orElse(ResponseEntity.notFound().build());
}Rather than scattering ResponseEntity checks everywhere, many applications define their own exception types for specific problems, then throw them from deep inside service code:
public class NotFoundException extends RuntimeException {
public NotFoundException(String message) {
super(message);
}
}A class annotated with @RestControllerAdvice can catch exceptions thrown by any controller in the application, translating them into a consistent response format:
@RestControllerAdvice
public class ErrorHandler {
@ExceptionHandler(NotFoundException.class)
public ResponseEntity<String> handle(NotFoundException e) {
return ResponseEntity.status(404).body(e.getMessage());
}
}With this in place, any part of the codebase can simply throw new NotFoundException("Item not found") and trust that it will turn into a proper 404 response, without repeating the same error-handling code in every controller method.
Bad input is one of the most common sources of errors, and Spring can reject it before a controller method even runs. Annotating a request body parameter with @Valid, combined with validation annotations on the class itself, triggers this automatically:
public class ProductForm {
@NotBlank
private String name;
@Positive
private double price;
}
@PostMapping("/products")
public Product create(@Valid @RequestBody ProductForm form) {
// only reached if validation passed
}A failed validation automatically produces a 400 Bad Request with details about which fields were invalid, all without a single explicit if statement in the controller.
Callers benefit greatly when every error, regardless of its cause, comes back in the same JSON shape, typically something like a timestamp, a message and a status field. Returning this consistent structure from the central @RestControllerAdvice class means a client only ever needs to write one piece of code to handle errors, instead of guessing the format for each different endpoint.
Good error handling is often invisible when everything works, but it is exactly what separates a rough prototype from an API other teams can build on with confidence, since predictable, well-described failures are far easier to debug and recover from than silent or malformed ones.