Bài 3: Xây dựng REST API với Spring MVC

# Mỗi request là độc lập — server không nhớ request trước
GET /api/users/1    → Server phản hồi với dữ liệu người dùng
GET /api/users/1    → Server phản hồi theo cách tương tự (không "nhớ" request đầu)

# Dùng danh từ, không dùng động từ — phương thức HTTP ĐÃ LÀ động từ
✅ GET /api/posts          (lấy tất cả bài viết)
❌ GET /api/getPosts       (thừa — GET đã có nghĩa "lấy")
❌ GET /api/posts/getAll   (thừa)

# Dùng danh từ số nhiều cho collection
✅ /api/posts
✅ /api/users
❌ /api/post               (số ít cảm giác không nhất quán)

# Dùng path variable cho tài nguyên cụ thể
✅ GET /api/posts/42       (lấy bài viết ID 42)

# Dùng query parameter cho lọc, sắp xếp, phân trang
✅ GET /api/posts?status=published&sort=date&page=2

# Dùng nesting cho tài nguyên con (quan hệ)
✅ GET /api/posts/42/comments       (tất cả bình luận của bài viết 42)
✅ GET /api/posts/42/comments/7     (bình luận 7 của bài viết 42)

# Giữ URL chữ thường, dùng dấu gạch nối cho nhiều từ
✅ /api/blog-posts
❌ /api/BlogPosts
❌ /api/blog_posts

@Controller
public class PageController {

    // Spring tìm template có tên "home" (ví dụ home.html trong thư mục templates)
    // và render nó thành trang HTML.
    @GetMapping("/home")
    public String homePage(Model model) {
        model.addAttribute("title", "Chào mừng đến Blog");
        model.addAttribute("posts", postService.getRecentPosts());
        return "home";  // Đây là TÊN VIEW, không phải dữ liệu
    }
}

@RestController
public class PostApiController {

    // Giá trị trả về (List<Post>) được tự động
    // serialize thành JSON và ghi vào phần thân response.
    @GetMapping("/api/posts")
    public List<Post> getAllPosts() {
        return postService.getAllPosts();  // Đây là DỮ LIỆU, không phải tên view
    }
}

// Dùng @RestController (phím tắt)
@RestController
public class PostApiController {

    @GetMapping("/api/posts")
    public List<Post> getAllPosts() {
        return postService.getAllPosts();
    }
}

// Dùng @Controller + @ResponseBody (cách dài)
@Controller
@ResponseBody
public class PostApiController {

    @GetMapping("/api/posts")
    public List<Post> getAllPosts() {
        return postService.getAllPosts();
    }
}

@RestController
@RequestMapping("/api/posts")  // Đường dẫn gốc cho tất cả phương thức trong controller
public class PostController {

    @GetMapping              // GET /api/posts
    public List<Post> getAll() { ... }

    @GetMapping("/{id}")     // GET /api/posts/42
    public Post getById(@PathVariable Long id) { ... }

    @PostMapping             // POST /api/posts
    public Post create(@RequestBody Post post) { ... }

    @PutMapping("/{id}")     // PUT /api/posts/42
    public Post update(@PathVariable Long id, @RequestBody Post post) { ... }

    @PatchMapping("/{id}")   // PATCH /api/posts/42
    public Post partialUpdate(@PathVariable Long id, @RequestBody Map<String, Object> updates) { ... }

    @DeleteMapping("/{id}")  // DELETE /api/posts/42
    public void delete(@PathVariable Long id) { ... }
}

// Hai cái này tương đương:
@GetMapping("/api/posts")
@RequestMapping(value = "/api/posts", method = RequestMethod.GET)

// Hai cái này tương đương:
@PostMapping("/api/posts")
@RequestMapping(value = "/api/posts", method = RequestMethod.POST)

GET /api/users/42          → 42 là path variable (ID người dùng)
GET /api/posts/15/comments → 15 là path variable (ID bài viết)

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

    // Một path variable
    // URL: GET /api/users/42
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // id = 42
        return userService.getUserById(id);
    }

    // Nhiều path variable
    // URL: GET /api/users/42/posts/15
    @GetMapping("/{userId}/posts/{postId}")
    public Post getUserPost(
            @PathVariable Long userId,
            @PathVariable Long postId) {
        // userId = 42, postId = 15
        return postService.getPostByUserAndId(userId, postId);
    }
}

GET /api/posts?status=published              → lọc theo trạng thái
GET /api/posts?sort=date&order=desc          → sắp xếp theo ngày giảm dần
GET /api/posts?page=2&size=10                → phân trang

@RestController
@RequestMapping("/api/posts")
public class PostController {

    // Query parameter bắt buộc
    // URL: GET /api/posts/search?keyword=spring
    @GetMapping("/search")
    public List<Post> search(@RequestParam String keyword) {
        return postService.searchByKeyword(keyword);
    }

    // Query parameter tùy chọn với giá trị mặc định
    // URL: GET /api/posts?page=2&size=20
    // URL: GET /api/posts (dùng mặc định: page=0, size=10)
    @GetMapping
    public List<Post> getAllPosts(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "10") int size) {
        return postService.getPosts(page, size);
    }

    // Tham số tùy chọn tường minh (có thể null)
    @GetMapping("/filter")
    public List<Post> filterPosts(
            @RequestParam(required = false) String status,
            @RequestParam(required = false) String category) {
        return postService.filterPosts(status, category);
    }
}

@RestController
@RequestMapping("/api/posts")
public class PostController {

    // Client gửi JSON trong phần thân request:
    // {
    //   "title": "Học Spring Boot",
    //   "content": "Spring Boot giúp lập trình web Java dễ dàng...",
    //   "category": "TUTORIAL"
    // }
    //
    // Spring đọc JSON này, tạo đối tượng Post, và gán giá trị cho các trường.
    // Quá trình này gọi là DESERIALIZATION (JSON → đối tượng Java).
    @PostMapping
    public Post createPost(@RequestBody Post post) {
        // Tại thời điểm này, post.getTitle() = "Học Spring Boot"
        // post.getContent() = "Spring Boot giúp lập trình web Java dễ dàng..."
        // post.getCategory() = "TUTORIAL"
        return postService.createPost(post);
    }
}

// PUT /api/posts/42
// Request body: { "title": "Tiêu đề cập nhật", "content": "Nội dung cập nhật" }
@PutMapping("/{id}")
public Post updatePost(
        @PathVariable Long id,           // Từ đường dẫn URL
        @RequestBody Post updatedPost) { // Từ phần thân request
    return postService.updatePost(id, updatedPost);
}

@RestController
@RequestMapping("/api/posts")
public class PostController {

    // POST /api/posts — Trả về 201 Created
    @PostMapping
    public ResponseEntity<Post> createPost(@RequestBody Post post) {
        Post created = postService.createPost(post);
        return ResponseEntity.status(HttpStatus.CREATED).body(created);
    }

    // GET /api/posts/42 — Trả về 200 OK hoặc 404 Not Found
    @GetMapping("/{id}")
    public ResponseEntity<Post> getPostById(@PathVariable Long id) {
        return postService.findById(id)
                .map(post -> ResponseEntity.ok(post))
                .orElse(ResponseEntity.notFound().build());
    }

    // DELETE /api/posts/42 — Trả về 204 No Content
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deletePost(@PathVariable Long id) {
        try {
            postService.deletePost(id);
            return ResponseEntity.noContent().build();
        } catch (RuntimeException e) {
            return ResponseEntity.notFound().build();
        }
    }
}

// 200 OK với body
ResponseEntity.ok(body)

// 201 Created với body
ResponseEntity.status(HttpStatus.CREATED).body(createdObject)

// 204 No Content
ResponseEntity.noContent().build()

// 400 Bad Request với body
ResponseEntity.badRequest().body(errorObject)

// 404 Not Found
ResponseEntity.notFound().build()

// Bất kỳ mã trạng thái nào
ResponseEntity.status(HttpStatus.CONFLICT).body(errorObject)

public class Post {

    private Long id;
    private String title;
    private String content;
    private String internalNotes;
    private LocalDateTime createdAt;

    // @JsonProperty — thay đổi tên trường JSON
    @JsonProperty("created_at")
    public LocalDateTime getCreatedAt() { return createdAt; }

    // @JsonIgnore — loại trừ trường này khỏi JSON hoàn toàn
    @JsonIgnore
    public String getInternalNotes() { return internalNotes; }
}

{
  "id": 1,
  "title": "Bài viết của tôi",
  "content": "Nội dung...",
  "created_at": "2024-01-15T10:30:00"
}
// "internalNotes" KHÔNG được bao gồm (vì @JsonIgnore)
// "createdAt" được serialize thành "created_at" (vì @JsonProperty)

// Phiên bản 1 — trả về thông tin người dùng cơ bản
@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 {

    @GetMapping("/{id}")
    public Map<String, Object> getUser(@PathVariable Long id) {
        return Map.of("id", id, "name", "Alice", "email", "alice@example.com");
    }
}

// Phiên bản 2 — trả về thông tin mở rộng với cấu trúc khác
@RestController
@RequestMapping("/api/v2/users")
public class UserControllerV2 {

    @GetMapping("/{id}")
    public Map<String, Object> getUser(@PathVariable Long id) {
        return Map.of(
            "id", id,
            "profile", Map.of("firstName", "Alice", "lastName", "Smith", "email", "alice@example.com"),
            "metadata", Map.of("createdAt", "2024-01-15", "lastLogin", "2024-06-20")
        );
    }
}

GET /api/v1/users/42  → định dạng cũ
GET /api/v2/users/42  → định dạng mới

package com.example.blogapi.model;

import com.fasterxml.jackson.annotation.JsonInclude;
import java.time.LocalDateTime;

@JsonInclude(JsonInclude.Include.NON_NULL)
public class Post {

    private Long id;
    private String title;
    private String content;
    private String category;
    private String status;          // "DRAFT" hoặc "PUBLISHED"
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;

    public Post() { }

    public Post(String title, String content, String category) {
        this.title = title;
        this.content = content;
        this.category = category;
        this.status = "DRAFT";
        this.createdAt = LocalDateTime.now();
    }

    // --- Getter và Setter ---
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getTitle() { return title; }
    public void setTitle(String title) { this.title = title; }
    public String getContent() { return content; }
    public void setContent(String content) { this.content = content; }
    public String getCategory() { return category; }
    public void setCategory(String category) { this.category = category; }
    public String getStatus() { return status; }
    public void setStatus(String status) { this.status = status; }
    public LocalDateTime getCreatedAt() { return createdAt; }
    public void setCreatedAt(LocalDateTime createdAt) { this.createdAt = createdAt; }
    public LocalDateTime getUpdatedAt() { return updatedAt; }
    public void setUpdatedAt(LocalDateTime updatedAt) { this.updatedAt = updatedAt; }
}

# Tạo bài viết
curl -X POST http://localhost:8080/api/posts \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Bắt đầu với Spring Boot",
    "content": "Spring Boot là framework giúp đơn giản hóa lập trình web Java...",
    "category": "TUTORIAL"
  }'
# Kết quả: 201 Created

# Lấy tất cả bài viết
curl http://localhost:8080/api/posts

# Cập nhật toàn bộ (PUT)
curl -X PUT http://localhost:8080/api/posts/1 \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Bắt đầu với Spring Boot 3",
    "content": "Spring Boot 3 yêu cầu Java 17...",
    "category": "TUTORIAL",
    "status": "PUBLISHED"
  }'

# Cập nhật một phần (PATCH) — chỉ cập nhật trạng thái
curl -X PATCH http://localhost:8080/api/posts/1 \
  -H "Content-Type: application/json" \
  -d '{"status": "PUBLISHED"}'

# Xóa bài viết
curl -X DELETE http://localhost:8080/api/posts/1 -v
# Kết quả: 204 No Content

{"id": 1, "title": "Tiêu đề gốc", "content": "Nội dung gốc", "category": "TUTORIAL", "status": "DRAFT"}