Mục tiêu
Sau bài này, bạn sẽ:
- Hiểu khái niệm REST API và các phương thức HTTP
- Biết các annotation cơ bản trong Spring MVC để xây dựng API
- Xây dựng được một CRUD API hoàn chỉnh cho một entity
- Test API thành công bằng Postman
Tham khảo chi tiết bài viết về Rest API tại https://tiilaz.com/lap-trinh/lap-trinh-android-java/api-la-gi-tai-sao-no-la-trai-tim-cua-moi-ung-dung-huong-dan-postman-tu-a-z/
1. REST API là gì?
REST (Representational State Transfer) là một phong cách kiến trúc để xây dựng API cho web.
Đặc điểm chính:
- Sử dụng các phương thức HTTP:
GET,POST,PUT,DELETE - URI đại diện cho tài nguyên (resource), ví dụ:
/products,/products/1 - Dữ liệu thường trả về dưới dạng JSON hoặc XML
- Không lưu trạng thái (stateless)
So với Servlet: với Servlet, bạn thường trả về JSP hoặc HTML. Với REST API, bạn trả về dữ liệu (JSON) để client (React, mobile, …) tự hiển thị.
2. Các annotation cơ bản trong Spring MVC
Trong Spring Boot, để xây dựng REST API, bạn sẽ dùng các annotation sau:
| Annotation | Mục đích |
|---|---|
@RestController | Đánh dấu class là controller, và tất cả các method trả về dữ liệu (JSON) thay vì tên view (kết hợp @Controller + @ResponseBody) |
@RequestMapping | Định nghĩa đường dẫn chung cho controller (ví dụ: /api/products) |
@GetMapping | Xử lý request HTTP GET |
@PostMapping | Xử lý request HTTP POST |
@PutMapping | Xử lý request HTTP PUT |
@DeleteMapping | Xử lý request HTTP DELETE |
@PathVariable | Lấy giá trị từ URL (ví dụ: /products/{id}) |
@RequestParam | Lấy tham số từ query string (ví dụ: /products?page=1) |
@RequestBody | Nhận dữ liệu JSON từ body của request và chuyển thành Java object |
3. So sánh với Servlet
Servlet thuần:
@WebServlet("/api/products/*")
public class ProductServlet extends HttpServlet {
protected void doGet(HttpServletRequest req, HttpServletResponse resp) {
// Lấy id từ URL, parse thủ công
// Lấy danh sách sản phẩm từ database
// Chuyển thành JSON bằng Gson/Jackson
// Ghi vào response
}
}Spring Boot:
@RestController
@RequestMapping("/api/products")
public class ProductController {
@GetMapping("/{id}")
public Product getProduct(@PathVariable Long id) {
return productService.findById(id); // Tự động convert sang JSON
}
}4. Thực hành: Xây dựng API quản lý sản phẩm
Chúng ta sẽ tạo một API đơn giản để quản lý danh sách sản phẩm (lưu trong bộ nhớ tạm – List).
Bước 1: Tạo class Product (Model)
package com.tiilaz.demoAPI.model;
public class Product {
private Long id;
private String name;
private Double price;
// Constructors, getters, setters
public Product() {}
public Product(Long id, String name, Double price) {
this.id = id;
this.name = name;
this.price = price;
}
// Getter và Setter
public Long getId() { return id; }
public void setId(Long id) { this.id = id; }
public String getName() { return name; }
public void setName(String name) { this.name = name; }
public Double getPrice() { return price; }
public void setPrice(Double price) { this.price = price; }
}Bước 2: Tạo Controller
package com.example.demo.controller;
import com.example.demo.model.Product;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.atomic.AtomicLong;
@RestController
@RequestMapping("/api/products")
public class ProductController {
// Giả lập database (lưu tạm trong list)
private List<Product> products = new ArrayList<>();
private AtomicLong idGenerator = new AtomicLong(1);
public ProductController() {
// Thêm vài sản phẩm mẫu khi khởi tạo
products.add(new Product(idGenerator.getAndIncrement(), "Laptop", 1200.0));
products.add(new Product(idGenerator.getAndIncrement(), "Mouse", 25.0));
}
// GET /api/products - Lấy danh sách tất cả sản phẩm
@GetMapping
public List<Product> getAllProducts() {
return products;
}
// GET /api/products/{id} - Lấy sản phẩm theo ID
@GetMapping("/{id}")
public Product getProductById(@PathVariable Long id) {
return products.stream()
.filter(p -> p.getId().equals(id))
.findFirst()
.orElse(null);
}
// POST /api/products - Thêm sản phẩm mới
@PostMapping
public Product createProduct(@RequestBody Product product) {
product.setId(idGenerator.getAndIncrement());
products.add(product);
return product;
}
// PUT /api/products/{id} - Cập nhật sản phẩm
@PutMapping("/{id}")
public Product updateProduct(@PathVariable Long id, @RequestBody Product product) {
for (int i = 0; i < products.size(); i++) {
if (products.get(i).getId().equals(id)) {
product.setId(id);
products.set(i, product);
return product;
}
}
return null;
}
// DELETE /api/products/{id} - Xóa sản phẩm
@DeleteMapping("/{id}")
public String deleteProduct(@PathVariable Long id) {
boolean removed = products.removeIf(p -> p.getId().equals(id));
return removed ? "Deleted" : "Not found";
}
}Bước 3: Chạy ứng dụng
- Chạy class
DemoApplication(main). - Mở Postman để test.
5. Test API với Postman
5.1. GET tất cả sản phẩm
- Method:
GET - URL:
http://localhost:8080/api/products - Kết quả:
[
{ "id": 1, "name": "Laptop", "price": 1200.0 },
{ "id": 2, "name": "Mouse", "price": 25.0 }
]5.2. GET sản phẩm theo ID
- Method:
GET - URL:
http://localhost:8080/api/products/1 - Kết quả:
{ "id": 1, "name": "Laptop", "price": 1200.0 }5.3. POST thêm sản phẩm mới
- Method:
POST - URL:
http://localhost:8080/api/products - Headers:
Content-Type: application/json - Body (raw JSON):
{
"name": "Keyboard",
"price": 45.0
}- Kết quả trả về sản phẩm đã được gán ID:
{ "id": 3, "name": "Keyboard", "price": 45.0 }5.4. PUT cập nhật sản phẩm
- Method:
PUT - URL:
http://localhost:8080/api/products/1 - Body:
{
"name": "Gaming Laptop",
"price": 1500.0
}- Kết quả:
{ "id": 1, "name": "Gaming Laptop", "price": 1500.0 }5.5. DELETE xóa sản phẩm
- Method:
DELETE - URL:
http://localhost:8080/api/products/2 - Kết quả:
"Deleted"
6. Giải thích thêm
@RestController: Thay vì dùng@Controller+@ResponseBodytrên mỗi method, ta dùng gộp.- Jackson: Spring Boot tự động dùng thư viện Jackson để chuyển đổi Java object ↔ JSON. Bạn không cần làm gì thêm.
- HTTP Status: Mặc định, thành công trả về 200 OK. Có thể tùy chỉnh bằng
ResponseEntity(sẽ học sau). - Xử lý lỗi: Hiện tại nếu không tìm thấy sản phẩm, trả về
null-> HTTP 200 với body rỗng. Trong thực tế, bạn nên trả về 404 (sẽ học ở bài nâng cao).
7. Bài tập
- Thêm trường
category(String) vào classProduct. Sửa các API để xử lý thêm trường này. - Tạo API tìm kiếm sản phẩm theo tên (dùng
@RequestParam):GET /api/products/search?name=laptrả về danh sách sản phẩm có tên chứa “lap”.
- (Nâng cao) Dùng
ResponseEntityđể trả về status 404 khi không tìm thấy sản phẩm.
8. Tóm tắt
- REST API là cách xây dựng web service trả về dữ liệu (JSON) thay vì giao diện.
- Spring Boot cung cấp các annotation đơn giản để tạo API nhanh chóng.
@RestController,@GetMapping,@PostMapping,… giúp code gọn và dễ hiểu.- Dữ liệu tự động chuyển đổi sang JSON nhờ Jackson.
