Implementing CRUD REST API with Spring Boot - Basic Structure of Controller, Service, and Repository

2026-04-02

Written by: Zuko

About this article

This article deepens your understanding of Spring Boot. A step-by-step guide to implementing CRUD (Create, Read, Update, Delete) REST API with Spring Boot. Build the three-layer architecture of Controller, Service, and Repository from scratch, and walk through setting up all four endpoints: GET, POST, PUT, and DELETE.

About the author View all Spring Boot articles

When building a REST API with Spring Boot, it’s easy to feel lost about how to connect the three layers — Controller, Service, and Repository. You might understand each annotation individually, but still have a fuzzy picture of how they all fit together.

In this article, we’ll build all four endpoints — GET, POST, PUT, and DELETE — using a simple Item entity as our example, walking through the full three-layer structure from start to finish. By the end, you’ll be ready to apply the same pattern to your own projects.

What We’re Building

Here’s the complete list of endpoints we’ll implement:

Method	Path	Description
GET	/items	Retrieve all items
GET	/items/{id}	Retrieve a single item
POST	/items	Create a new item
PUT	/items/{id}	Update an item
DELETE	/items/{id}	Delete an item

The package structure will be organized as follows:

src/main/java/com/example/demo/
├── controller/
│   └── ItemController.java
├── service/
│   └── ItemService.java
├── repository/
│   └── ItemRepository.java
└── entity/
    └── Item.java

Project Setup

Go to Spring Initializr and create a project with Spring Web, Spring Data JPA, and H2 Database. The following dependencies will be added to your pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

Add the H2 configuration to application.properties. Since it’s an in-memory database, it’s perfect for verifying behavior during development.

spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driver-class-name=org.h2.Driver
spring.h2.console.enabled=true
spring.jpa.show-sql=true

Responsibilities of Each Layer

Before diving into the implementation, let’s clarify the role of each layer:

Controller — The entry point that receives HTTP requests and returns responses. No business logic here.
Service — Where business logic lives. Calls the Repository to perform data operations.
Repository — Abstracts database access. Spring Data JPA auto-generates the implementation.

Dependencies flow in one direction: Controller → Service → Repository. If a Controller directly accesses the Repository, or business logic leaks into the Controller, changes become painful down the road.

Defining the Entity Class

package com.example.demo.entity;

import jakarta.persistence.*;

@Entity
@Table(name = "items")
public class Item {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String name;

    private String description;

    // getters / setters omitted (Lombok's @Data works too)
}

@Entity registers the class with JPA, and @Id with @GeneratedValue configures auto-incrementing IDs.

Defining the Repository

Simply extend JpaRepository:

package com.example.demo.repository;

import com.example.demo.entity.Item;
import org.springframework.data.jpa.repository.JpaRepository;

public interface ItemRepository extends JpaRepository<Item, Long> {
}

This alone gives you findAll(), findById(), save(), and deleteById(). If you need custom query conditions, refer to the Spring Data JPA query methods article.

Implementing the Service Class

package com.example.demo.service;

import com.example.demo.entity.Item;
import com.example.demo.repository.ItemRepository;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class ItemService {

    private final ItemRepository itemRepository;

    public ItemService(ItemRepository itemRepository) {
        this.itemRepository = itemRepository;
    }

    public List<Item> findAll() {
        return itemRepository.findAll();
    }

    public Item findById(Long id) {
        return itemRepository.findById(id)
                .orElseThrow(() -> new RuntimeException("Item not found: " + id));
    }

    public Item create(Item item) {
        return itemRepository.save(item);
    }

    public Item update(Long id, Item item) {
        Item existing = findById(id);
        existing.setName(item.getName());
        existing.setDescription(item.getDescription());
        return itemRepository.save(existing);
    }

    public void delete(Long id) {
        itemRepository.deleteById(id);
    }
}

Constructor injection is the approach recommended by Spring. It makes tests easier to write compared to using @Autowired on fields.

The places where RuntimeException is thrown should, in production code, be replaced with custom exceptions and centralized using @ControllerAdvice, as covered in the exception handling article.

Implementing the Controller

package com.example.demo.controller;

import com.example.demo.entity.Item;
import com.example.demo.service.ItemService;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/items")
public class ItemController {

    private final ItemService itemService;

    public ItemController(ItemService itemService) {
        this.itemService = itemService;
    }

    @GetMapping
    public ResponseEntity<List<Item>> findAll() {
        return ResponseEntity.ok(itemService.findAll());
    }

    @GetMapping("/{id}")
    public ResponseEntity<Item> findById(@PathVariable Long id) {
        return ResponseEntity.ok(itemService.findById(id));
    }

    @PostMapping
    public ResponseEntity<Item> create(@RequestBody Item item) {
        return ResponseEntity.status(HttpStatus.CREATED).body(itemService.create(item));
    }

    @PutMapping("/{id}")
    public ResponseEntity<Item> update(@PathVariable Long id, @RequestBody Item item) {
        return ResponseEntity.ok(itemService.update(id, item));
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@PathVariable Long id) {
        itemService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

The choice of HTTP status codes is important:

POST → 201 Created (a new resource was created)
DELETE → 204 No Content (success, but no response body)
Successful reads and updates → 200 OK

@RequestBody deserializes the request JSON into an object, and @PathVariable captures {id} from the URL.

To add input validation, just add @Valid before @RequestBody and annotate your entity fields with constraints like @NotBlank. See the validation article for details.

Testing with curl

Start the app with mvn spring-boot:run and verify behavior using curl:

# Create data (returns 201 Created)
curl -X POST http://localhost:8080/items \
  -H "Content-Type: application/json" \
  -d '{"name":"テスト商品","description":"説明文"}'

# Retrieve all items
curl http://localhost:8080/items

# Retrieve a single item
curl http://localhost:8080/items/1

# Update an item
curl -X PUT http://localhost:8080/items/1 \
  -H "Content-Type: application/json" \
  -d '{"name":"更新後の商品","description":"更新済み"}'

# Delete an item (returns 204 No Content)
curl -X DELETE http://localhost:8080/items/1

The H2 console is accessible at http://localhost:8080/h2-console. Enter jdbc:h2:mem:testdb as the JDBC URL.

Next Steps

Now that you have basic CRUD working, here are some additions to bring it closer to production quality:

Centralized exception handling → See the exception handling article for how to use @ControllerAdvice
Pagination → For designs that scale as data grows, see the pagination article
Entity relationships → For working with multiple tables, see the JPA entity relationship mapping article
Auto-generated API documentation → Consider adding Swagger UI as covered in the OpenAPI/Swagger article

Summary

We’ve implemented a complete CRUD API using a three-layer architecture. Keeping the responsibilities of each layer separate makes it straightforward to add exception handling and validation later — you always know exactly where to make changes. Start by applying this structure to your own project and build on it from there.

References

Official documentation and references for the topics covered in this article.

Implementing CRUD REST API with Spring Boot - Basic Structure of Controller, Service, and Repository

What We’re Building

Project Setup

Responsibilities of Each Layer

Defining the Entity Class

Defining the Repository

Implementing the Service Class

Implementing the Controller

Testing with curl

Next Steps

Summary

References

Related Articles

How to Write Unit Tests for Controllers Using MockMvc in Spring Boot

How to Standardize Error Responses with Problem Details (RFC 9457) in Spring Boot 3.x

How to Use GraphQL with Spring Boot - Spring for GraphQL Basics and When to Use It vs REST API

How to Automate Entity-DTO Mapping with MapStruct in Spring Boot

More Articles

How to Achieve Graceful Shutdown and Zero-Downtime Deployment in Spring Boot

Implementing Kafka Producer and Consumer with Spring Boot