Spring Boot REST API for Beginners: Build Your First Endpoint

Spring Boot is a Java framework that removes most of the setup work from building web applications and APIs. It gives you sensible defaults, an embedded web server and a large ecosystem, so you can focus on your own code. This guide walks through a first REST endpoint. You should already be comfortable with Java classes and interfaces, so if not, start with Java OOP concepts explained.

What you need

• A recent JDK. Current Spring Boot versions require Java 17 or newer, so check the requirement for the version you choose in the official documentation.
• A build tool: Maven or Gradle. The generator below creates the project for either.
• An editor or IDE such as IntelliJ IDEA, Eclipse or VS Code with Java support.

Step 1: Generate a project

Go to the Spring Initializr website (start.spring.io), choose Maven or Gradle, pick Java, and add the Spring Web dependency. Download the project, unzip it and open it in your IDE. The generated class annotated with @SpringBootApplication is your entry point.

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

Spring Web includes an embedded server, so you do not install a separate one. Running this class starts the application, by default on port 8080.

Step 2: Write a controller

Create a new class in the same package as the application class or in a sub-package. Spring scans from the application class's package downward, so a class outside it will not be found.

@RestController
@RequestMapping("/api/greetings")
public class GreetingController {

    @GetMapping
    public String hello() {
        return "Hello from Spring Boot";
    }

    @GetMapping("/{name}")
    public String helloName(@PathVariable String name) {
        return "Hello, " + name;
    }
}

• @RestController marks the class as a web controller whose return values are written to the response body.
• @RequestMapping sets a base path for every method in the class.
• @GetMapping maps HTTP GET requests, and @PathVariable reads a value from the URL.

Step 3: Return JSON

Return an object instead of a string and Spring converts it to JSON.

public record Greeting(String message) {}

@GetMapping("/json/{name}")
public Greeting greeting(@PathVariable String name) {
    return new Greeting("Hello, " + name);
}

Step 4: Accept a request body

Use @PostMapping and @RequestBody to read JSON sent by a client.

@PostMapping
public ResponseEntity<Greeting> create(@RequestBody Greeting greeting) {
    return ResponseEntity.status(HttpStatus.CREATED).body(greeting);
}

Returning ResponseEntity lets you control the status code. Creating a resource is normally answered with 201, and the REST API design guide explains when to use each status.

Step 5: Run and test

Start the application from your IDE or with the build tool's Spring Boot run command. Then open http://localhost:8080/api/greetings/Asha in a browser, or call the POST endpoint with a tool such as curl or Postman. To change the port, set server.port in application.properties.

Common beginner mistakes

• Putting the controller outside the application class's package, so it is never scanned.
• Using @Controller and getting a "view not found" error when you meant @RestController.
• Forgetting the Spring Web dependency, so the annotations are not available.
• Building large controllers that mix HTTP handling, business rules and database code. Split the responsibilities using controller, service and repository layers.

Key takeaways

• Generate the project with Spring Initializr and add Spring Web.
• @RestController plus mapping annotations define endpoints.
• Return objects to get JSON, and use ResponseEntity for status codes.
• Keep controllers thin. Sharpen your Java foundations with the Object-Oriented Java quiz.