Building a REST API with Spring Boot (Beginner Guide)

Now we get to the heart of modern backend development: building a REST API. This is what most Spring Boot jobs are actually about — creating the server-side endpoints that power mobile apps, single-page websites, and other services. By the end of this lesson you'll understand what REST means and how to build a complete set of CRUD endpoints. This is the skill employers hire for.

What is a REST API, really?

A REST API is a set of web endpoints that let clients (apps, websites, other servers) create, read, update, and delete data over HTTP. "REST" is just a popular style/convention for designing these endpoints so they're predictable. The core idea: you have resources (like "users" or "posts"), and you act on them using standard HTTP methods.

These four map neatly onto CRUD (Create, Read, Update, Delete) — the four things almost every app does with data. Data is usually exchanged as JSON, a simple text format Spring converts to and from Java objects automatically.

Building a complete REST controller

Let's build a real controller for a "User" resource. Notice how each method matches a row from the table above:

@RestController
@RequestMapping("/api/users")   // base path for all endpoints here
public class UserController {

    private final UserService service;
    public UserController(UserService service) { this.service = service; }

    @GetMapping                               // GET /api/users
    public List<User> getAll() {
        return service.findAll();
    }

    @GetMapping("/{id}")                       // GET /api/users/5
    public User getOne(@PathVariable Long id) {
        return service.findById(id);
    }

    @PostMapping                              // POST /api/users
    @ResponseStatus(HttpStatus.CREATED)      // return 201 Created
    public User create(@RequestBody User user) {
        return service.save(user);
    }

    @PutMapping("/{id}")                       // PUT /api/users/5
    public User update(@PathVariable Long id, @RequestBody User user) {
        return service.update(id, user);
    }

    @DeleteMapping("/{id}")                    // DELETE /api/users/5
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable Long id) {
        service.delete(id);
    }
}

That's a complete CRUD API. Spring does the heavy lifting: it routes each URL to the right method, converts incoming JSON into a User object (@RequestBody), and converts your returned objects back into JSON responses. You just write the logic.

The pieces working together

• @PathVariable pulls the {id} out of the URL into a method parameter.
• @RequestBody turns the JSON the client sent into a Java object.
• Return values become the JSON response automatically — return a User, the client gets JSON.
• @ResponseStatus sets the HTTP status code (201 for created, 204 for deleted, etc.).

Layered design: keep controllers thin

Notice the controller doesn't do the actual work — it delegates to a UserService. This is a key best practice:

A quick word on status codes

REST APIs communicate outcomes with HTTP status codes: 200 OK, 201 Created, 204 No Content (deleted), 400 Bad Request (client error), 404 Not Found, 500 Server Error. Returning the right code is part of a well-designed API — clients rely on them. We'll dig into error responses in the exception handling lesson.

Building my first full CRUD API was the moment Spring Boot's value became undeniable to me — a handful of annotated methods, and I had a real backend that a frontend or mobile app could talk to. The thing I want you to take away is the pattern: it's the same four operations, mapped to the same four HTTP methods, every single time. Once you've built one CRUD controller, you've essentially built them all. This website's admin panel is dozens of these controllers working together. Build one yourself, hit it from your browser or a tool like Postman, and watch the JSON flow — that's backend development clicking into place.

Key takeaways

• A REST API exposes resources over HTTP using GET/POST/PUT/DELETE — mapping to CRUD.
• Build endpoints with @RestController + mapping annotations; @RequestBody and return values handle JSON conversion automatically.
• Use the right HTTP status codes (200/201/204/404…) to communicate outcomes.
• Keep controllers thin — delegate to services; follow Controller → Service → Repository layering.

← Previous: Spring Lesson 4 — Essential Annotations
Next: Spring Lesson 6 — Spring Data JPA (Databases) →
↑ Back to the Spring Boot roadmap