Spring

Spring Boot Tutorial for Beginners: From Zero to a Running REST API (Spring Boot 4.1)

A Spring Boot 4.1 tutorial for beginners: set up, run your first app, understand controllers, services and repositories, configuration and validation, then follow a map of 80+ deeper guides.

Ankur Oct 21, 2026 12 min read

Spring Boot is a way to build Java applications with almost no setup: you add one dependency, write a class with main, and you have a running web server. It does this by looking at what is on your classpath and configuring Spring (the framework underneath) to match. This tutorial takes you from nothing to a working REST endpoint, then hands you a map of 82 deeper guides on this site, grouped by what you want to do next.

You will learn	Section
What you need installed	1
The smallest app that runs	2
How a request becomes a response	3
Layers: controller, service, repository	4
Configuration and validation	5
Where to go next (map of 82 guides)	6

Tested on Spring Boot 4.1.1, Java 21 (OpenJDK 21.0.12), Maven. Every output block below is from a real run of the demo app: DemoApplication.java, Components.java and More.java. Boot 4 needs Java 17 or newer; on a new project use the latest LTS (Java 21 or 25). Check Spring Boot versions for support dates.

1. What you need

A JDK (Java 21 is a good choice), Maven or Gradle, and an editor. Check with java -version and mvn -v. To create a project, either use start.spring.io (pick Maven, Java, Spring Boot 4.1.x, and the Spring Web dependency) or copy the pom from spring-boot-annotation-demo-pom.xml.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.1</version>
    <relativePath/>
  </parent>
  <groupId>demo</groupId>
  <artifactId>demo</artifactId>
  <version>1.0.0</version>
  <properties><java.version>21</java.version></properties>
  <dependencies>
    <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-webmvc</artifactId></dependency>
    <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency>
  </dependencies>
  <build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>
</project>

Source: spring-boot-annotation-demo-pom.xml. Notice there is no version on the dependencies. The spring-boot-starter-parent parent chooses compatible versions for you, and a starter such as spring-boot-starter-webmvc pulls in everything needed for web apps (Spring MVC, Tomcat, JSON). The Spring vs Spring Boot vs Spring MVC post measures what that saves.

2. The smallest app that runs

One class is enough. @SpringBootApplication turns on component scanning and auto-configuration; SpringApplication.run starts the container and the embedded server:

package demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

Source: DemoApplication.java. Run it with mvn spring-boot:run or build the jar and run java -jar. The lines that matter in the startup log:

2026-10-21T21:33:55.071+05:30  INFO 1569 --- [           main] o.apache.catalina.core.StandardEngine    : Starting Servlet engine: [Apache Tomcat/11.0.24]
2026-10-21T21:33:55.665+05:30  INFO 1569 --- [           main] o.s.boot.tomcat.TomcatWebServer          : Tomcat started on port 8080 (http) with context path '/'
2026-10-21T21:33:55.679+05:30  INFO 1569 --- [           main] demo.DemoApplication                     : Started DemoApplication in 2.705 seconds (process running for 3.357)

Tomcat is up on port 8080, started inside your own process; there is no separate server to install. The three annotations hiding in @SpringBootApplication are listed with real output in the annotations list.

3. How a request becomes a response

A client sends HTTP to Tomcat. Spring MVC’s DispatcherServlet looks at the URL and calls the matching controller method. The controller asks a service, the service asks a repository, and the return value travels back as the response. Each box is an ordinary class. Spring creates them, and hands each one the next as a constructor argument (dependency injection).

4. Controller, service, repository

Start from the bottom. The repository returns data (here a fixed list), the service uses it, and the controller exposes it. Mark each with its stereotype annotation so Spring finds and creates them:

@Repository
class ItemRepository {
    List<String> findAll() { return List.of("pen", "book", "lamp"); }
}

@Service
class ItemService {
    private final ItemRepository repo;
    ItemService(ItemRepository repo) { this.repo = repo; }
    List<String> items() { return repo.findAll(); }
}

Source: Components.java. ItemService asks for an ItemRepository in its constructor and Spring supplies it. That is all that dependency injection is. Prefer constructor injection; Dependency Injection in Spring Boot 4: Constructor vs Setter vs Field (and Why Field Injection Hurts) shows why field injection hurts.

@RestController
@RequestMapping("/api")
class ItemController {
    private final ItemService service;
    private final Notifier primary;
    private final Notifier sms;
    private final AppProps props;
    @Value("${app.greeting}") String greeting;

    ItemController(ItemService service, Notifier primary, @Qualifier("sms") Notifier sms, AppProps props) {
        this.service = service; this.primary = primary; this.sms = sms; this.props = props;
    }

    @GetMapping("/items")
    List<String> items() { return service.items(); }

    @GetMapping("/items/{index}")
    String one(@PathVariable int index, @RequestParam(defaultValue = "plain") String style) {
        return style + ":" + service.items().get(index);
    }
    // ...other handlers in the file
}

Source: Components.java. @RestController says return values are the response body. Try it:

$ curl localhost:8080/api/items
["pen","book","lamp"]
$ curl localhost:8080/api/items/1?style=bold
bold:book

{index} in the path is a path variable and style is a query parameter, and Spring converted 1 to an int for you. Pass something that is not a number and you get a 400, not a 500:

$ curl localhost:8080/api/items/abc
{"timestamp":"2026-10-21T16:04:04.715Z","status":400,"error":"Bad Request","path":"/api/items/abc"}
HTTP 400

5. Configuration and validation

Settings live in src/main/resources/application.properties. The demo has two lines, app.greeting and app.max-items, read two ways: @Value for one property and a @ConfigurationProperties record for the group:

$ curl localhost:8080/api/config
{"props.maxItems":5,"value":"Hello from properties","props.greeting":"Hello from properties"}

Source: Components.java. Profiles, config import and environment variables are in Spring Boot Profiles Done Right: Config Import, Config Trees and Kubernetes ConfigMaps and @ConfigurationProperties vs @Value in Spring Boot 4: Binding, Validation and Relaxed Rules.

Reject bad input at the edge with Bean Validation: put @Valid on the @RequestBody and constraints on the record. The invalid body below never reaches your method:

$ curl -XPOST -H "Content-Type: application/json" -d {"name":"","qty":0} localhost:8080/api/new
{"timestamp":"2026-10-21T16:04:04.682Z","status":400,"error":"Bad Request","path":"/api/new"}
HTTP 400

Source: More.java. By default the 400 body does not say which field failed; Global Exception Handling with ProblemDetail (RFC 9457) in Spring Boot 4 shows how to return a proper error document.

6. Where to go next

Everything below is a tested guide on this site. Pick the section that matches what you are building. If you do not know yet, do the first two groups, then the project structure and CRUD with MySQL posts, then build one of the 10 project ideas or the microservices project.

Core concepts: beans, injection, configuration

Building REST APIs

Data and persistence

Messaging, async and batch

Security

Testing

Running in production

Architecture

Upgrading and versions

Interview preparation

Common interview questions

What is Spring Boot and why use it?

A framework layer on Spring that auto-configures the application, embeds a server and provides starters, so you can build a production-ready service with minimal setup.

What is the difference between Spring and Spring Boot?

Spring is the framework; Boot configures it for you. See Spring vs Spring Boot vs Spring MVC.

What does @SpringBootApplication do?

It enables component scanning, auto-configuration and marks the class as a configuration class.

What is a Spring Boot starter?

A dependency that bundles the libraries for one purpose, such as spring-boot-starter-webmvc for web apps.

How does auto-configuration work?

Boot checks the classpath and your beans and registers defaults for what it finds, backing off when you define your own bean. Write your own starter shows the mechanism.

Common mistakes

Putting the main class in the default package. Component scanning starts in the main class’s package; keep controllers and services under it.
Using field injection with @Autowired. Use a constructor.
Putting business logic in the controller. Keep controllers thin; see project structure.
Not pinning the Boot version to a supported line. Boot 3.x is end of life; see versions.
Exposing internal errors. The default 400/404 bodies hide details; add a global handler.

FAQ

How long does it take to learn Spring Boot?

The tutorial above gets a first endpoint running in minutes; the next two weeks are beans, configuration, data access and tests.

Do I need to learn Spring before Spring Boot?

No. Learn Boot first and the Spring concepts under it as they appear.

Which Java version does Spring Boot 4 need?

Java 17 or newer; Java 21 or 25 are the sensible LTS choices. See Spring Boot versions.

Is Spring Boot good for microservices?

Yes; see the microservices project and Modular Monolith vs Microservices in 2026: A Java Decision Framework.