It is time to write code. In this lesson you will generate the ciclourbana project with Spring Initializr —both from the web and from the command line—, open it in your IDE and create the platform's first real endpoint: GET /api/v1/stations, which will return the list of stations in the Ribalta network. You will then run it in three different ways, exercise it with curl and package it into an executable JAR that runs with java -jar without installing any server. By the end you will have an API working end to end.

1. Spring Initializr: what it is and how to use it
2. Generating the project from the web
3. Generating the project from the command line
4. Importing the project into the IDE
5. The generated startup class
6. The first endpoint: GET /api/v1/stations
7. Running the application
8. Testing the endpoint with curl
9. Packaging and running the JAR
10. Spring Boot DevTools and automatic restart
11. Common Mistakes and Tips
12. Exercises

Spring Initializr (start.spring.io) is the official Spring Boot project generator. You give it four details and a list of dependencies, and it hands you back a ZIP containing:

• A pom.xml already configured with the Spring Boot parent and the dependencies you chose.
• The main application class, annotated and ready to start.
• A basic test class.
• The Maven wrapper (mvnw, mvnw.cmd, .mvn/).
• A suitable .gitignore and an empty application.properties.

It is the right way to start any Spring Boot project. Creating the structure by hand is possible, but it is unnecessary work and error-prone.

Open https://start.spring.io and fill the form in with these exact values, which we will use for the whole course:

In the Dependencies panel, click "ADD DEPENDENCIES" and add exactly two:

• Spring Web — Spring MVC, Jackson for JSON and an embedded Tomcat. This is what turns the project into a web application.
• Spring Boot DevTools — automatic restart on code changes and cache deactivation during development.

Click GENERATE. ciclourbana.zip downloads. Unzip it wherever you keep your projects.

One tip before downloading: the EXPLORE button shows the project's contents without downloading it, and SHARE produces a URL that reproduces exactly that configuration. It is very handy for sharing a starting point with a colleague.

Spring Initializr is also an HTTP API. That lets you generate the project without opening a browser and —more importantly— keep the command in the team's documentation so anyone can reproduce the same starting point.

A breakdown of the curl options:

• -d key=value sends a form parameter. Using -d makes curl issue a POST request automatically.
• dependencies=web,devtools is the comma-separated list of dependency identifiers. web corresponds to "Spring Web" and devtools to "Spring Boot DevTools".
• -o ciclourbana.zip saves the response to a file instead of dumping it to the terminal.

Two very useful exploratory commands:

If you omit bootVersion, Initializr uses the latest stable release, which is usually what you want.

The project is a standard Maven project, so any IDE understands it.

IntelliJ IDEA: File → Open and select the ciclourbana folder (not the bare pom.xml, although that works too). IntelliJ detects the pom.xml, indexes the project and downloads the dependencies. You will see a progress bar at the bottom right; wait for it to finish.

Eclipse / STS: File → Import → Maven → Existing Maven Projects, select the root folder and click Finish.

VS Code: File → Open Folder on ciclourbana. The Java extension starts on its own and a Spring Boot Dashboard view appears in the sidebar.

In all three cases, the first import takes a while: Maven downloads the Spring dependencies into ~/.m2/repository. That is a few hundred megabytes the first time and practically instantaneous from then on.

Open src/main/java/com/ciclourbana/CiclourbanaApplication.java. It contains this:

It is ten lines, but every one of them matters:

• @SpringBootApplication is the annotation that switches everything on. It bundles three annotations we will study in module 2: it enables autoconfiguration, marks the class as a source of configuration and activates component scanning starting from this package.
• main is an ordinary Java main method. A Spring Boot application is, literally, a Java program that starts from its main. There is no external container invoking it.
• SpringApplication.run(...) creates the Spring context, registers the beans and —on detecting Spring Web— starts Tomcat. It returns the running context. What happens inside, step by step, is the subject of lesson 01-05.
• The args argument is propagated: it lets you pass parameters from the command line, such as --server.port=9090.

For consistency with the rest of the course, rename the class to CicloUrbanaApplication (with a capital U). Use the IDE's rename refactoring (Shift+F6 in IntelliJ) so that it updates the test file as well.

We are going to expose Ribalta's stations. We need two pieces: a type representing a station and a controller that returns it as JSON.

Java 21 offers records, ideal for immutable data. Create the file src/main/java/com/ciclourbana/stations/Station.java:

Why a record and not a regular class:

• It automatically generates the constructor, the accessor methods (name(), capacity()...), equals, hashCode and toString.
• It is immutable: once created it does not change, which avoids errors in concurrent environments.
• Jackson, the library Spring Boot uses to turn objects into JSON, has understood records for several versions now. Each component becomes a JSON property with the same name.

Create src/main/java/com/ciclourbana/stations/StationController.java:

What each annotation does, at just the right depth for this lesson:

• @RestController marks the class as a Spring component that handles HTTP requests and whose methods return the response body directly (not the name of an HTML view). Spring finds the class while scanning the package and registers it.
• @RequestMapping("/api/v1/stations") sets the base path for every method in the class. That way the prefix is written only once.
• @GetMapping with no arguments maps the method to GET on the exact base path, that is, GET /api/v1/stations.
• The method returns a List<Station>. Thanks to Jackson, Spring Boot converts it automatically into a JSON array and sets the Content-Type: application/json header. Nothing has to be serialised by hand.

The fine detail of these annotations, content negotiation, status codes and parameter handling is covered in depth in module 3. Here it is enough that it works.

There are three ways, and it is worth knowing all three.

This is the canonical way from the terminal:

spring-boot:run compiles the project and starts the application in the same JVM as Maven, with no need to package it. It is the most convenient option during development.

The output ends with something along these lines:

The three key lines: the Java version in use, the port 8080 Tomcat is listening on, and the startup time. We will read this log line by line in lesson 01-05.

To stop the application, Ctrl+C.

Open CicloUrbanaApplication and run the main method like any Java program: the green triangle in IntelliJ, Run As → Java Application in Eclipse, or Run on the main in VS Code.

The advantage of the IDE is the debugger: you can set a breakpoint in listStations() and watch execution stop when the request arrives.

STS and VS Code also offer a Spring Boot Dashboard to start, stop and restart without hunting for the class.

This is the production route, and we cover it in section 9.

With the application running, open another terminal:

Response:

To see it readably and with the headers:

The response with -i starts like this:

Notice that you have not written a single line about JSON or about the 200 status code. Spring Boot inferred the Content-Type from the return type and applied 200 by default. That is autoconfiguration at work.

Try a non-existent path too, to see the default error behaviour:

Spring Boot returns a structured error body without you configuring anything. Customising it is the goal of lesson 03-06.

This command cleans the target folder, compiles, runs the tests and produces the JAR. When it finishes:

Two files appear, and the difference explains everything:

• .jar.original (12 KB) is the JAR Maven produces in the standard way: only your compiled classes.
• .jar (22 MB) is the fat jar, or uber jar: your classes plus every dependency —Spring, Jackson, Tomcat— plus a special loader.

The spring-boot-maven-plugin is what performs that transformation during the package phase.

An ordinary JAR is a ZIP of .class files. To run it you need all its dependencies on the classpath, which forces you to ship dozens of files or to install an application server.

Spring Boot solves this with an ingenious format:

You can check it yourself:

The manifest reveals the trick:

When you run the JAR, Java invokes Spring Boot's JarLauncher, not your class. That launcher installs a class loader capable of reading nested JARs inside BOOT-INF/lib —something standard Java cannot do— and only then calls your Start-Class.

The practical consequence is enormous: a single file contains the complete application, server included. That is what gets copied onto a server, put into a Docker image or uploaded to a cloud platform.

It starts up exactly as it did with spring-boot:run. Check that it still responds:

You can pass properties on the command line:

Note the difference: -Xmx256m goes before -jar because it is a JVM option, whereas --server.port=9090 goes after because it is an application argument.

When we generated the project we added spring-boot-devtools:

The <optional>true</optional> and <scope>runtime</scope> attributes mean DevTools is not propagated to anyone depending on your project and that it switches itself off automatically when the application runs from a fat jar. In other words: it helps during development and vanishes in production without you doing a thing.

What it brings:

DevTools uses two class loaders: a base one with the dependencies (Spring, Tomcat, Jackson), which never change, and a restart one with your classes, which do. On restart it only discards and reloads the second one. That is why it takes tenths of a second instead of the two seconds of a full startup.

That is also why the main thread appears in the log as restartedMain instead of main.

The restart is triggered when the .class files in target/classes change, not when you save the .java. So a recompile is required:

• IntelliJ: Ctrl+F9 (Build Project), or enable Settings → Build → Compiler → Build project automatically.
• Eclipse/STS: compiles on save by default, so Ctrl+S is enough.
• VS Code: also compiles on save.

Try it. With the application running via ./mvnw spring-boot:run, add a fifth station:

Recompile and watch the log:

Now curl returns five stations without you having stopped anything.

If the restart gets in your way, you can switch it off without removing the dependency:

• Web server failed to start. Port 8080 was already in use. You have another instance running, which is very typical if you forgot to stop the one in the IDE before launching ./mvnw spring-boot:run. Find the process with lsof -i :8080 (Linux/macOS) or netstat -ano | findstr :8080 (Windows), or start on a different port with --server.port=9090.
• The endpoint returns 404 even though the code looks right. It is almost always because the controller sits outside the root package com.ciclourbana. Component scanning only looks at that package and its subpackages; we will see this in lesson 01-04.
• The application starts and exits immediately. spring-boot-starter-web is missing. Without a web dependency there is no server to keep the process alive, so main finishes and the JVM shuts down.
• DevTools restarts nothing. You are saving the .java but it is not being recompiled. Enable automatic building in the IDE or compile by hand.
• Running the .jar.original by mistake. It gives no main manifest attribute. The right file is the large .jar, with no suffix.
• Tip — the JAR is self-contained, not standalone. It carries every Java dependency, but it still needs a JVM installed wherever it runs. That is why Spring Boot Docker images start from an image with a JDK or JRE (module 7).
• Tip — initialise Git now. The project comes with a correct .gitignore. With git init && git add . && git commit -m "Initial CicloUrbana project" you will have a safe point to return to from day one.

Generate the ciclourbana project from the command line with curl, run it and use curl to check that GET /api/v1/stations returns Ribalta's four stations. Note down the startup time shown in the log.

Add a second endpoint GET /api/v1/stations/summary to StationController that returns a JSON object with the total number of stations and the total capacity of the network. Use a record NetworkSummary.

Package the application, inspect the contents of the fat jar to locate your compiled classes and the embedded Tomcat JAR, and run it on port 9090, checking that it responds.

Solution 1

After creating Station and StationController as described in the lesson:

In another terminal:

The startup time appears on the Started CicloUrbanaApplication in X seconds line. On a normal machine it is between 1.5 and 3 seconds.

Solution 2

First the summary record, in the same package:

And the new method in the controller:

A detailed explanation:

• @GetMapping("/summary") is concatenated with the class-level @RequestMapping, producing GET /api/v1/stations/summary.
• Station::capacity is a method reference. In a record, the accessor has the same name as the component (capacity(), not getCapacity()).
• mapToInt(...).sum() turns the stream into an IntStream and adds up the values, avoiding autoboxing.
• Returning an object (not a list) makes Jackson produce a JSON object rather than an array.

Checking it:

Solution 3

Verification in another terminal:

The takeaway from this exercise: your classes live in BOOT-INF/classes and the dependencies in BOOT-INF/lib as nested JARs. That separation is exactly what allows Spring Boot to build efficient layered Docker images, something we will take advantage of in module 7.

CicloUrbana is up and running. You have generated the project with Spring Initializr from the web and from the terminal, understood the ten lines of the startup class, created the Station record and the StationController that exposes GET /api/v1/stations with Ribalta's four stations, and run it with Maven, with the IDE and as a self-contained fat jar via java -jar. You also know why that JAR weighs 22 MB and how the JarLauncher loads the nested JARs in BOOT-INF/lib.

In the next lesson, Understanding the Project Structure, we will open the box: we will walk through the generated directory tree, read the pom.xml line by line, understand exactly what a starter is and why the root package determines which components Spring finds, and design the package layout CicloUrbana will keep for the whole course.