Spring Boot Course · Lesson 1

Your First Running Endpoint

Set up a professional Java toolchain, then go from an empty folder to a live HTTP endpoint you built — all from the command line. This is the foundation every other lesson stands on.

Why Spring Boot exists

You already know Java. So why a framework? Because a real backend needs a web server, JSON handling, configuration, database connections, and a hundred wires connecting them. Plain Spring can do all of this, but historically it meant pages of XML and manual setup.

Spring Boot is the answer to "make Spring just work." It is opinionated: it ships sensible defaults, bundles an embedded server right inside your app, and uses auto-configuration to wire things up based on what's on your classpath. ^[docs] You write business logic; it handles the plumbing.

Step 0 — Prerequisites

Everything in this lesson runs from a terminal. The tooling below expects a few standard command-line utilities to already be on your machine: curl (to download installers), zip and unzip (SDKMAN unpacks its downloads with them), and git (to version your project). Check them once:

curl --version
zip --version
unzip -v
git --version

If any command prints command not found, install the missing pieces for your OS:

# curl, zip and unzip ship with macOS. git comes with the Xcode Command Line Tools:
xcode-select --install

sudo apt-get update
sudo apt-get install -y curl zip unzip git

Step 1 — Install Java with SDKMAN

Before any Spring code, you need a JDK. The cleanest way to manage Java on macOS or Linux is SDKMAN! — it installs JDKs (and other JVM tools) and lets you switch versions per project without ever editing PATH or JAVA_HOME by hand. ^[docs]

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"   # or just open a new terminal

Now install a JDK. We'll use Temurin 21, the current long-term-support release:

sdk install java 21-tem      # download + install Temurin 21 (LTS)
sdk default java 21-tem      # make it your default
java -version                # verify — should report 21

Run sdk list java to browse every distribution and version. The -tem suffix is Eclipse Temurin; 21 is the version. Anything 17+ works for this course.

Step 2 — Generate the project from the command line

Never hand-write a Spring Boot project — generate it. The web UI at start.spring.io (Spring Initializr) is great for browsing options, but its command-line twin is faster once you know what you want. Install the Spring Boot CLI through SDKMAN:

sdk install springboot
spring --version             # verify the CLI is on your PATH

Now generate the Library project in one command:

spring init \
  --dependencies=web \
  --build=maven \
  --java-version=21 \
  --group-id=com.example \
  --artifact-id=library \
  --name=library \
  --package-name=com.example.library \
  --extract library

This drops a ready-to-run project into a new library/ folder. Each flag maps to a field you'd otherwise click in the web UI: --dependencies=web adds the Spring Web starter, --build=maven picks Maven, and --extract unzips into the folder instead of leaving a .zip. Open library/ in IntelliJ IDEA (or VS Code / Eclipse).

Under the hood, spring init just calls start.spring.io for you — same generator, no browser. Run spring init --list to see every available dependency and option. Prefer clicking? The web Initializr produces an identical project.

1
java=21-tem

Step 3 — Read the two files that matter

Initializr gives you a runnable app already. Two pieces make it tick.

1
package com.example.library;
2

3
import org.springframework.boot.SpringApplication;
4
import org.springframework.boot.autoconfigure.SpringBootApplication;
5

6
@SpringBootApplication
7
public class LibraryApplication {
8
    public static void main(String[] args) {
9
        SpringApplication.run(LibraryApplication.class, args);
10
    }
11
}

That's a normal Java main method. The magic is one annotation: @SpringBootApplication. It turns on auto-configuration and tells Spring to scan this package for your components. SpringApplication.run(...) boots the container and starts the embedded web server. ^[guide]

Step 4 — Write your endpoint

Create a new file next to LibraryApplication.java:

1
package com.example.library;
2

3
import org.springframework.web.bind.annotation.GetMapping;
4
import org.springframework.web.bind.annotation.RestController;
5

6
@RestController
7
public class HelloController {
8

9
    @GetMapping("/hello")
10
    public String hello() {
11
        return "Hello from the Library API!";
12
    }
13
}

Two annotations are doing all the work:

• @RestController — tells Spring this class handles web requests, and that whatever a method returns is written straight into the HTTP response body. A String like ours is sent as-is (plain text); return an object or a list instead and Spring turns it into JSON automatically — that's Lesson 2.
• @GetMapping("/hello") — routes GET /hello to this method. ^[guide]

Notice you never registered this class anywhere. Component scanning (from @SpringBootApplication) finds @RestController and turns it into a managed bean automatically.

Step 5 — Run it

Run main from your IDE, or from the project root:

# macOS / Linux
./mvnw spring-boot:run

Watch the console: you'll see the Spring banner, then a line like Tomcat started on port 8080 and Started LibraryApplication. That "Tomcat" is the embedded server — running inside your Java process. Now open:

http://localhost:8080/hello

You should see your message. That's a real web service, and you built it.

Check yourself

Retrieval beats re-reading. Answer from memory before clicking.

Read this next

Primary source: the official guide Building a RESTful Web Service (≈15 min). It covers exactly what you just did, from the Spring team itself — read it to reinforce, and notice how it returns an object (which becomes JSON) instead of a plain string. That's where Lesson 2 picks up.

Glossary: the terms this lesson introduces are in the Glossary, under Lesson 1 — your quick-reference for every term we use.

Architecture decisions: the 5 choices this lesson makes, each with its reason, are in Architecture Decisions, under Lesson 1.

Code: the project at the end of this lesson, exercises included.

💬 Discuss