Spring Boot REST API

GET    /api/tasks        -> list all tasks
GET    /api/tasks/42     -> get task 42
POST   /api/tasks        -> create a new task
DELETE /api/tasks/42     -> delete task 42

<dependencies>
    <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>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

spring.application.name=task-api
spring.datasource.url=jdbc:h2:mem:tasks
spring.jpa.open-in-view=false

HTTP request (JSON)
      │
      ▼
┌──────────────────┐   receives requests, validates input, returns responses
│ TaskController   │
└────────┬─────────┘
         ▼
┌──────────────────┐   business rules and transactions
│ TaskService      │
└────────┬─────────┘
         ▼
┌──────────────────┐   reads and writes the database
│ TaskRepository   │
└────────┬─────────┘
         ▼
     Database

package com.javabytechie.tasks;

import java.time.Instant;
import java.time.LocalDate;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;

@Entity
@Table(name = "tasks")
public class Task {

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

    @Column(nullable = false, length = 100)
    private String title;

    @Column(length = 500)
    private String description;

    private boolean completed;

    private LocalDate dueDate;

    @Column(nullable = false, updatable = false)
    private Instant createdAt = Instant.now();

    protected Task() {
        // required by JPA
    }

    public Task(String title, String description, LocalDate dueDate) {
        this.title = title;
        this.description = description;
        this.dueDate = dueDate;
    }

    public void update(String title, String description, LocalDate dueDate) {
        this.title = title;
        this.description = description;
        this.dueDate = dueDate;
    }

    public void markCompleted() {
        this.completed = true;
    }

    public Long getId() { return id; }
    public String getTitle() { return title; }
    public String getDescription() { return description; }
    public boolean isCompleted() { return completed; }
    public LocalDate getDueDate() { return dueDate; }
    public Instant getCreatedAt() { return createdAt; }
}

public record TaskRequest(

        @NotBlank(message = "Title is required")
        @Size(max = 100, message = "Title must be at most 100 characters")
        String title,

        @Size(max = 500, message = "Description must be at most 500 characters")
        String description,

        @FutureOrPresent(message = "Due date cannot be in the past")
        LocalDate dueDate
) {
}

public record TaskResponse(
        Long id,
        String title,
        String description,
        boolean completed,
        LocalDate dueDate,
        Instant createdAt
) {
    public static TaskResponse from(Task task) {
        return new TaskResponse(task.getId(), task.getTitle(), task.getDescription(),
                task.isCompleted(), task.getDueDate(), task.getCreatedAt());
    }
}

public interface TaskRepository extends JpaRepository<Task, Long> {

    List<Task> findByCompleted(boolean completed);

    Page<Task> findByCompleted(boolean completed, Pageable pageable);
}

public class TaskNotFoundException extends RuntimeException {

    public TaskNotFoundException(Long id) {
        super("Task " + id + " does not exist");
    }
}

package com.javabytechie.tasks;

import java.util.List;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
@Transactional
public class TaskService {

    private final TaskRepository taskRepository;

    public TaskService(TaskRepository taskRepository) {
        this.taskRepository = taskRepository;
    }

    @Transactional(readOnly = true)
    public List<TaskResponse> findAll(Boolean completed) {
        List<Task> tasks = (completed == null)
                ? taskRepository.findAll()
                : taskRepository.findByCompleted(completed);
        return tasks.stream().map(TaskResponse::from).toList();
    }

    @Transactional(readOnly = true)
    public TaskResponse findById(Long id) {
        return TaskResponse.from(getTask(id));
    }

    public TaskResponse create(TaskRequest request) {
        Task task = new Task(request.title(), request.description(), request.dueDate());
        return TaskResponse.from(taskRepository.save(task));
    }

    public TaskResponse update(Long id, TaskRequest request) {
        Task task = getTask(id);
        task.update(request.title(), request.description(), request.dueDate());
        return TaskResponse.from(task);   // saved automatically when the transaction commits
    }

    public TaskResponse complete(Long id) {
        Task task = getTask(id);
        task.markCompleted();
        return TaskResponse.from(task);
    }

    public void delete(Long id) {
        taskRepository.delete(getTask(id));
    }

    private Task getTask(Long id) {
        return taskRepository.findById(id).orElseThrow(() -> new TaskNotFoundException(id));
    }
}

package com.javabytechie.tasks;

import java.net.URI;
import java.util.List;

import jakarta.validation.Valid;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.support.ServletUriComponentsBuilder;

@RestController
@RequestMapping("/api/tasks")
public class TaskController {

    private final TaskService taskService;

    public TaskController(TaskService taskService) {
        this.taskService = taskService;
    }

    @GetMapping
    public List<TaskResponse> list(@RequestParam(required = false) Boolean completed) {
        return taskService.findAll(completed);
    }

    @GetMapping("/{id}")
    public TaskResponse get(@PathVariable Long id) {
        return taskService.findById(id);
    }

    @PostMapping
    public ResponseEntity<TaskResponse> create(@Valid @RequestBody TaskRequest request) {
        TaskResponse created = taskService.create(request);
        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
                .path("/{id}")
                .buildAndExpand(created.id())
                .toUri();
        return ResponseEntity.created(location).body(created);   // 201 + Location header
    }

    @PutMapping("/{id}")
    public TaskResponse update(@PathVariable Long id, @Valid @RequestBody TaskRequest request) {
        return taskService.update(id, request);
    }

    @PatchMapping("/{id}/complete")
    public TaskResponse complete(@PathVariable Long id) {
        return taskService.complete(id);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable Long id) {
        taskService.delete(id);
    }
}

curl -i -X POST http://localhost:8080/api/tasks \
     -H "Content-Type: application/json" \
     -d '{"title": "Write REST tutorial", "description": "Cover CRUD and testing", "dueDate": "2026-12-01"}'

HTTP/1.1 201 Created
Location: http://localhost:8080/api/tasks/1
Content-Type: application/json

{
  "id": 1,
  "title": "Write REST tutorial",
  "description": "Cover CRUD and testing",
  "completed": false,
  "dueDate": "2026-12-01",
  "createdAt": "2026-10-04T09:15:42.381Z"
}

# List all tasks, or only open ones
curl http://localhost:8080/api/tasks
curl "http://localhost:8080/api/tasks?completed=false"

# Get one task
curl http://localhost:8080/api/tasks/1

# Update it
curl -X PUT http://localhost:8080/api/tasks/1 \
     -H "Content-Type: application/json" \
     -d '{"title": "Write REST API tutorial", "dueDate": "2026-12-05"}'

# Mark it as completed
curl -X PATCH http://localhost:8080/api/tasks/1/complete

# Delete it (prints the 204 status line)
curl -i -X DELETE http://localhost:8080/api/tasks/1

@RestControllerAdvice
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(TaskNotFoundException.class)
    public ProblemDetail handleNotFound(TaskNotFoundException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        problem.setTitle("Task not found");
        return problem;
    }
}

{
  "type": "about:blank",
  "title": "Task not found",
  "status": 404,
  "detail": "Task 99 does not exist",
  "instance": "/api/tasks/99"
}

public record PageResponse<T>(
        List<T> content,
        int page,
        int size,
        long totalElements,
        int totalPages
) {
    public static <T> PageResponse<T> from(Page<T> page) {
        return new PageResponse<>(page.getContent(), page.getNumber(), page.getSize(),
                page.getTotalElements(), page.getTotalPages());
    }
}

@GetMapping("/paged")
public PageResponse<TaskResponse> listPaged(
        @PageableDefault(size = 20, sort = "createdAt", direction = Sort.Direction.DESC) Pageable pageable) {
    return PageResponse.from(taskService.findPage(pageable));
}

@Transactional(readOnly = true)
public Page<TaskResponse> findPage(Pageable pageable) {
    return taskRepository.findAll(pageable).map(TaskResponse::from);
}

curl "http://localhost:8080/api/tasks/paged?page=0&size=10&sort=dueDate,asc"

@WebMvcTest(TaskController.class)
@Import(ApiExceptionHandler.class)
class TaskControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockitoBean
    private TaskService taskService;

    @Test
    void returnsTaskAsJson() throws Exception {
        TaskResponse task = new TaskResponse(1L, "Write tests", null, false, null, Instant.now());
        when(taskService.findById(1L)).thenReturn(task);

        mockMvc.perform(get("/api/tasks/1"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.title").value("Write tests"));
    }

    @Test
    void returns404ForUnknownTask() throws Exception {
        when(taskService.findById(99L)).thenThrow(new TaskNotFoundException(99L));

        mockMvc.perform(get("/api/tasks/99"))
                .andExpect(status().isNotFound())
                .andExpect(jsonPath("$.title").value("Task not found"));
    }

    @Test
    void rejectsTaskWithoutTitle() throws Exception {
        mockMvc.perform(post("/api/tasks")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"title": "", "description": "No title"}
                                """))
                .andExpect(status().isBadRequest());

        verifyNoInteractions(taskService);   // invalid input never reaches the service
    }
}

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>${springdoc.version}</version>
</dependency>