Build a Spring Boot RESTful API from Scratch: Step‑by‑Step Guide

1. Create a Spring Boot project

Open an IDE such as IntelliJ IDEA or Eclipse.

Select “New Spring Boot Project”.

In the project initializer, add the Spring Web dependency, which brings in Spring MVC and other essentials for building RESTful APIs.

2. Create a controller class

Under src/main/java create a new Java file named UserController.java:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/")
    public String getUsers() {
        return "Hello, Users!";
    }
}

@RestController

marks the class as a REST controller, causing method return values to be written directly to the HTTP response body. @RequestMapping("/api/users") defines a base path for all endpoints in this controller. @GetMapping("/") maps GET requests to /api/users/ and returns a simple greeting string.

3. Run the application

Run the main class annotated with @SpringBootApplication:

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

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

@SpringBootApplication

is a composite annotation that includes @Configuration, @EnableAutoConfiguration, and @ComponentScan, enabling automatic configuration and component scanning. SpringApplication.run(Application.class, args) boots the Spring context and starts the embedded server.

4. Test the API

Open a browser or use a tool like Postman to request http://localhost:8080/api/users/. The response should be the plain text “Hello, Users!”.

5. Add more API endpoints

Extend UserController with additional CRUD methods:

import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/")
    public String getUsers() {
        return "Hello, Users!";
    }

    @GetMapping("/{id}")
    public String getUserById(@PathVariable Long id) {
        return "User with id: " + id;
    }

    @PostMapping("/")
    public String createUser(@RequestBody String user) {
        return "Creating user: " + user;
    }

    @PutMapping("/{id}")
    public String updateUser(@PathVariable Long id, @RequestBody String user) {
        return "Updating user with id: " + id + " with " + user;
    }

    @DeleteMapping("/{id}")
    public String deleteUser(@PathVariable Long id) {
        return "Deleting user with id: " + id;
    }
}

@GetMapping("/{id}")

handles GET requests with a path variable {id}. @PostMapping("/") handles POST requests; @RequestBody binds the request payload to the method parameter. @PutMapping("/{id}") handles PUT requests for updating a resource. @DeleteMapping("/{id}") handles DELETE requests for removing a resource.

6. Optional: configure application properties

You can change the server port or other settings in src/main/resources/application.properties or application.yml:

server.port=8081

server:
  port: 8081

7. Optional: add service and repository layers

Example service class:

import org.springframework.stereotype.Service;

@Service
public class UserService {
    public String getUserById(Long id) {
        return "User with id: " + id;
    }
}

Inject the service into the controller:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/{id}")
    public String getUserById(@PathVariable Long id) {
        return userService.getUserById(id);
    }
}

These optional steps illustrate how to structure a more maintainable Spring Boot application by separating concerns into controller, service, and repository layers.