Build your first REST API with Java and Spring Boot

The application will run exclusively on your computer. You need a JDK, not just a runtime: the JDK includes the compiler and tools Maven uses. This project pins Java 25 and Spring Boot 4.1.0; the PHP campus never compiles or executes the code you write.

Minimum checks

Install an OpenJDK 25 distribution from a trusted provider. Open a new terminal and run java -version and javac -version. Both outputs must begin with 25. If they do not match, check JAVA_HOME and the order of PATH before changing the project.

Reproducible Wrapper

The repository includes mvnw, mvnw.cmd and .mvn/wrapper/maven-wrapper.properties. This is the official mode only-script: on its first run it downloads Maven 3.9.16, then reuses that distribution. On macOS or Linux, use ./mvnw -version; in Windows PowerShell, use .\mvnw.cmd -version.

Reading the structure

src/main/java contains production code, src/main/resources configuration, src/test/java tests and pom.xml the build model. The IDE imports the POM, but the terminal is the reproducible reference.

HTTP is the exchange protocol. REST is a style for organising resources and using HTTP semantics; it does not mean that any JSON at a URL is REST.

Anatomy of an interaction

A request contains a method, URI, headers and sometimes a body. A response contains a state, headers and a representation. In GET /api/v1/tareas, the client requests a collection. In POST /api/v1/tareas, it requests creation of an item from the supplied JSON.

Semantics that matter

GET is safe: it is not intended to modify state. It is also idempotent: repeating it has the same effect, although data may change between reads. POST is not idempotent by definition; two submissions can create two resources. Successful creation returns 201 and a header named Location. An invalid JSON belongs to the 400 group; a non-existent route must not be disguised as 200.

The exercise's Contract

GET /api/v1/tareas          -> 200 + JSON list
GET /api/v1/tareas/{id}     -> 200 or 404
POST /api/v1/tareas         -> 201 + task + Location
POST with an empty title   -> 400 + problem+json

The version v1 forms part of the path to make the contract visible. It does not solve an evolution strategy by itself, but avoids silently changing things for consumers.

The project already includes a foundation so that it does not depend on a web generator. The parent spring-boot-starter-parent:4.1.0 manages compatible versions. spring-boot-starter-webmvc includes Spring MVC and the server; spring-boot-starter-validation includes Jakarta Validation.

Main class and packages

PrimeraApiApplication is in the root package com.kintavor.primeraapi. @SpringBootApplication enables configuration, auto-configuration and scanning of descendant packages. If you move the class outside the root package, Spring may stop discovering controllers and services.

First start-up

Run ./mvnw spring-boot:run or .\mvnw.cmd spring-boot:run. Look for port 8080 and a start-up without exceptions. Stop with Ctrl+C; avoid forcibly closing the terminal when an orderly shutdown is possible.

What auto-configuration does

Boot examines available classes and configuration and creates suitable infrastructure. It does not generate your business rules. If the port is occupied, temporarily use --spring-boot.run.arguments=--server.port=8081; do not kill unfamiliar processes.

Run ./mvnw test before and after each step. A successful build does not prove that the HTTP contract is correct, but eliminates one category of failures.

The controller translates HTTP; it must not become a store or a business rule. TareaService temporarily stores tasks in memory, and TareaResponse defines what is exposed.

Route and response

@GetMapping
List<TareaResponse> listar() {
  return service.listar().stream().map(TareaResponse::from).toList();
}

The class annotation supplies /api/v1/tareas. Because the operation completes normally, Spring serialises the list and responds with 200 and JSON. A record is suitable for a small DTO because it declares its components without setters.

Separate models

Tarea represents the internal data. TareaResponse represents the external contract. Although their fields are currently similar, separating them prevents an internal change from accidentally exposing new information.

Manual test

With the application running, execute curl -i http://localhost:8080/api/v1/tareas. Check the state, Content-Type and that the response is an array. On Windows, you can use Invoke-RestMethod. Save the exact request in your notebook: a screenshot without the command is not enough to reproduce the result.

POST receives an intention to create. @RequestBody converts the JSON into CrearTareaRequest; the service assigns an identity, and the controller returns the created representation.

Implementation

@PostMapping
ResponseEntity<TareaResponse> crear(
    @Valid @RequestBody CrearTareaRequest request,
    UriComponentsBuilder uris) {
  Tarea creada = service.crear(request.titulo(), request.descripcion());
  URI location = uris.path("/api/v1/tareas/{id}")
      .buildAndExpand(creada.id()).toUri();
  return ResponseEntity.created(location).body(TareaResponse.from(creada));
}

The identifier is assigned on the server; accepting an arbitrary client id would introduce collisions and ambiguous rules. The Location header identifies the created resource, and the body avoids forcing the client to make another request to see it.

Manual test

curl -i -X POST http://localhost:8080/api/v1/tareas \
  -H 'Content-Type: application/json' \
  -d '{"titulo":"Leer sobre HTTP","descripcion":"Anotar estados"}'

Repeat the submission deliberately: two resources are created because we have not designed idempotence. This is a property that a real business case must decide, rather than a framework error.

Validation prevents impossible data from entering the application. The DTO declares shape and size; the service normalises; a global handler converts known exceptions into consistent responses.

Input Constraints

public record CrearTareaRequest(
  @NotBlank @Size(max = 80) String titulo,
  @Size(max = 300) String descripcion
) {}

@Valid activates these constraints when receiving the body. A title containing only spaces fails. The size limit protects contract and resources, although a real API would also limit the total body size on the server.

Problem Details

@RestControllerAdvice transforms MethodArgumentNotValidException into state 400 and adds errors for each field. The external response does not contain a stack trace. TareaNoEncontradaException is translated to 404: the request was valid, but the resource does not exist.

Two levels

Jakarta Validation checks shape at the boundary. The invariants that must hold even without HTTP belong in the domain or service. Copying the same rule into every controller creates inconsistencies.

Test an empty title, an 81-character title and a non-existent id. All three failures must be predictable and must not stop the process.

A manual check helps exploration; an automated test preserves the contract. The solution uses MockMvc to exercise routing, JSON, validation and controller without opening a port, and a unit test for the in-memory service.

The verification cycle

1. Predict the result and run ./mvnw test.
2. Read the first failure, rather than the last line.
3. Reduce the change and rerun one specific test.
4. Run the complete suite before finishing.

A useful assertion checks the state and important data. Checking only that a response exists would allow silent errors. The validation test also demonstrates that the service does not accept a body without a title.

What this demo does not attempt to solve

Data disappears on restart. There is no PostgreSQL, authentication, roles, transactions, pagination, OpenAPI or deployment. This limitation is deliberate: first understand the complete HTTP flow, then replace the store without distorting the contract.

Conclusion

Complete the five exercises, take the diagnostics and compare your version with solution.zip only after recording your decisions. The solution is a reference, rather than the only valid implementation.