Tạo Web API đầu tiên

Bạn đã biết HTTP, giờ tới lúc tự dựng một server trả lời request. Bài này tạo project Web API bằng Spring Boot, chạy nó, và gọi thử server vừa dựng.

Khái niệm

🏗️ Web API: chương trình chạy trên server, nhận HTTP request và trả về dữ liệu (thường là JSON) thay vì trang web.

🌱 Spring Boot: framework Java để viết ứng dụng web, tự cấu hình sẵn server và thư viện để bạn chỉ viết phần của mình.

📦 Maven: công cụ tải thư viện, compile và chạy project Java, đọc cấu hình từ file pom.xml.

Ví dụ

Tải project mẫu từ Spring Initializr (start.spring.io), giải nén rồi vào thư mục. Lệnh curl gõ trên một dòng, và trên Windows vẫn gõ curl.exe:

curl https://start.spring.io/starter.tgz -d type=maven-project -d javaVersion=25 -d dependencies=web,validation -d groupId=com.shop -d artifactId=shop-api -d packageName=com.shop.api -d baseDir=shop-api -o shop-api.tgz
tar -xzf shop-api.tgz
cd shop-api

• dependencies=web,validation thêm Spring Web để viết Web API, và thư viện kiểm tra dữ liệu.

Thêm dòng sau vào src/main/resources/application.properties để server luôn chạy ở http://localhost:5000:

server.port=5000

Chạy server (PowerShell gõ .\mvnw spring-boot:run):

./mvnw spring-boot:run

• mvnw là Maven đi kèm project. Lần đầu nó tải thư viện, mất vài phút.
• Server chạy cho tới khi bạn bấm Ctrl+C.

Phần cốt lõi của src/main/java/com/shop/api/ShopApiApplication.java, file Initializr tạo sẵn:

// ShopApiApplication.java
package com.shop.api;

import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;

@SpringBootApplication
public class ShopApiApplication {
    public static void main(String[] args) {
        SpringApplication.run(
            ShopApiApplication.class, args);
    }
}

• main viết dạng đầy đủ như mọi project Java, vẫn là nơi chương trình bắt đầu chạy.
• @SpringBootApplication bật cấu hình tự động và bảo Spring tìm class của bạn trong package com.shop.api.
• SpringApplication.run(...) khởi động server và bắt đầu nhận request.
• Initializr ghi từng import đầy đủ. Khoá này viết gọn bằng dấu * để dòng code không quá dài.
• Khi trả object về cho client, Spring Boot đổi nó sang JSON, tên lấy theo getter: getPrice() thành "price".

Cứ giữ nguyên pom.xml và thư mục src/test, lúc này chưa cần sửa.

Thử ngay

Project mới chưa có code xử lý URL nào. Để nguyên server đang chạy, mở terminal thứ hai và gọi:

curl -i http://localhost:5000/api/products

Đoán trước khi chạy: server đang chạy nhưng chưa biết URL này. Status code là bao nhiêu, và body có gì?

HTTP/1.1 404
Content-Type: application/json

{"timestamp":"2026-09-29T04:11:48.584Z","status":404,"error":"Not Found","path":"/api/products"}

Lỗi hay gặp

Xoá @SpringBootApplication. Code vẫn compile được, nhưng ứng dụng dừng ngay lúc khởi động, báo không tìm thấy web server (ServletWebServerFactory).

// SAI — ứng dụng dừng ngay khi khởi động
// ShopApiApplication.java
package com.shop.api;

import org.springframework.boot.*;

public class ShopApiApplication {
    public static void main(String[] args) {
        SpringApplication.run(
            ShopApiApplication.class, args);
    }
}

// ĐÚNG
// ShopApiApplication.java
package com.shop.api;

import org.springframework.boot.*;
import org.springframework.boot.autoconfigure.*;

@SpringBootApplication
public class ShopApiApplication {
    public static void main(String[] args) {
        SpringApplication.run(
            ShopApiApplication.class, args);
    }
}

Đặt class ngoài package com.shop.api. Server vẫn chạy, nhưng URL của class đó trả 404, vì Spring chỉ tìm class trong package của @SpringBootApplication và các package con.

Tóm tắt

• Spring Initializr (start.spring.io) tạo project, dependencies=web,validation thêm Spring Web và thư viện kiểm tra dữ liệu.
• server.port=5000 trong application.properties cố định địa chỉ server.
• ./mvnw spring-boot:run chạy server (PowerShell: .\mvnw spring-boot:run).
• @SpringBootApplication và SpringApplication.run khởi động ứng dụng.
• Mọi class phải nằm trong package com.shop.api.