HTTP và REST là gì: gọi API đầu tiên bằng curl và Postman
HTTP và REST là gì? Hiểu request, response, các phương thức GET, POST, DELETE và status code qua một API đơn hàng viết bằng Java, gọi thử bằng curl.
HTTP là cách ứng dụng nói chuyện với máy chủ: bên gửi gửi một request, bên nhận trả lại một response. REST là cách đặt tên các request đó cho gọn: đường dẫn nói làm việc với thứ gì, phương thức nói muốn làm gì, mã trạng thái nói kết quả ra sao.
Mình bắt đầu từ chuyện quán cà phê Mộc, ví dụ xuyên suốt loạt bài này (đây là tình huống minh họa, không có quán nào thật). Chủ quán có một ứng dụng đặt món trên điện thoại. Khi khách bấm đặt, ứng dụng cần gửi đơn đến một chương trình chạy trên máy chủ để lưu lại, và chương trình đó chính là phần backend mà loạt bài này sẽ cùng xây. Trước khi viết một dòng code Spring nào, bạn cần hiểu cách ứng dụng và máy chủ nói chuyện với nhau. Đó là việc của bài này.
Nếu bạn chưa biết Java, bạn vẫn đọc được bài này, vì mình chỉ dùng Java để dựng một máy chủ rất nhỏ. Nếu bạn muốn học Java trước, hãy xem trang series Học Java từ đầu cho người làm backend.
Một lần gọi HTTP gồm những gì?
HTTP là giao thức dạng "hỏi một câu, đáp một câu". Bên hỏi (gọi là client, ví dụ ứng dụng trên điện thoại hay trình duyệt) gửi một request. Bên đáp (server, máy chủ) gửi lại một response. Cả hai đều là văn bản có cấu trúc cố định.
Cách tốt nhất để thấy nó là nhìn trực tiếp. Mình đã dựng sẵn một máy chủ nhỏ (code ở phần sau) và dùng curl, công cụ dòng lệnh để gửi request, với cờ -v để in cả hai chiều. Dòng bắt đầu bằng > là những gì client gửi đi, dòng bắt đầu bằng < là những gì server trả về:
curl -sv http://localhost:8080/orders/2> GET /orders/2 HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.77.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Date: Mon, 16 Nov 2026 08:07:27 GMT
< Content-type: application/json; charset=utf-8
< Content-length: 61
<Request gồm ba phần. Dòng đầu tiên, GET /orders/2 HTTP/1.1, gọi là request line: nó nói phương thức (GET), đường dẫn (/orders/2) và phiên bản giao thức. Các dòng tiếp theo là header, những thông tin phụ như máy chủ nào (Host), ai gửi (User-Agent). Phần cuối là body, nội dung gửi kèm; request này là GET nên không có body.
Response có cấu trúc tương tự. Dòng đầu là status line, HTTP/1.1 200 OK, trong đó 200 là mã trạng thái (status code) và OK là chữ mô tả. Tiếp theo là header của response, ví dụ Content-type: application/json cho biết nội dung trả về là JSON, và Content-length: 61 cho biết nó dài 61 byte. Sau một dòng trống mới đến body, tức là phần dữ liệu thật mà mình cố tình lược đi ở trên (bạn sẽ thấy nó ở phần dưới).
Hai điều cần nhớ. Một là chỉ có client mới chủ động gửi request, server không tự gửi đến client (tạm hiểu vậy, ở mức bài này). Hai là mỗi request độc lập: server không "nhớ" request trước, trừ khi bạn tự thiết kế để nhớ. Điều này sẽ quan trọng khi mình làm đăng nhập ở các bài sau.
REST là gì, và nó khác HTTP ở chỗ nào?
HTTP là giao thức, tức là luật về cách gửi và nhận. REST (Representational State Transfer) là một phong cách thiết kế API chạy trên HTTP, do Roy Fielding mô tả trong luận án tiến sĩ năm 2000. Nó không phải một chuẩn bắt buộc hay một công nghệ cài đặt được. Khi người ta nói "REST API" trong công việc hằng ngày, họ thường muốn nói một API dùng HTTP, trao đổi dữ liệu dạng JSON và tuân theo vài quy ước. Ba quy ước quan trọng nhất cho người mới là:
Thứ nhất, mỗi thứ mà API quản lý (ở đây là đơn hàng) là một tài nguyên có đường dẫn riêng, viết bằng danh từ. Đơn hàng thì là /orders, một đơn cụ thể thì là /orders/2. Không viết /getOrder hay /deleteOrder, vì "làm gì" đã có chỗ riêng ở điểm tiếp theo.
Thứ hai, phương thức HTTP nói hành động. GET để đọc, POST để tạo mới, PUT để thay thế toàn bộ, PATCH để sửa một phần, DELETE để xóa. Cùng một đường dẫn /orders/2 nhưng GET là xem, còn DELETE là xóa.
Thứ ba, mã trạng thái nói kết quả. Client đọc con số này để biết chuyện gì xảy ra mà không phải đoán qua nội dung chữ. Các mã bạn sẽ gặp thường xuyên là 200 (thành công), 201 (đã tạo), 204 (thành công và không có gì để trả về), 400 (request sai), 404 (không tìm thấy), 405 (phương thức không được hỗ trợ) và 500 (server lỗi). Danh sách đầy đủ và ý nghĩa chuẩn nằm trong RFC 9110 và tài liệu HTTP trên MDN.
Có một tính chất của các phương thức mà phỏng vấn hay hỏi: GET, PUT và DELETE là idempotent, nghĩa là gọi một lần hay gọi nhiều lần liên tiếp thì kết quả trên server vẫn như nhau (xóa đơn số 1 hai lần thì đơn vẫn chỉ biến mất một lần). POST thì không: gọi hai lần sẽ tạo ra hai đơn. Vì vậy khi mạng chập chờn và client gửi lại một POST, đơn có thể bị tạo trùng. Mình sẽ quay lại vấn đề này ở chặng sau, khi nói về idempotency key.
Dựng một API đơn hàng bằng Java để thử
Thay vì chỉ đọc lý thuyết, mình dựng một máy chủ thật. Mình dùng đúng bộ JDK bạn vừa cài (xem bài cài JDK và chạy chương trình Java đầu tiên) vì nó có sẵn một máy chủ HTTP nhỏ, nên không cần thư viện nào. Từ bài sau mình sẽ chuyển sang Spring Boot, nhưng muốn hiểu Spring làm gì giúp bạn thì nên một lần tự làm tay.
Máy chủ này giữ vài đơn hàng trong bộ nhớ và có bốn chức năng: xem danh sách, xem một đơn, tạo đơn, xóa đơn. Mỗi đơn dùng dạng rút gọn gồm bốn trường: id, customer (tên khách), item (món) và quantity (số lượng). Bạn tạo một file tên OrderServer.java trong một thư mục trống và dán toàn bộ đoạn sau vào:
import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
public class OrderServer {
// record: cách khai báo gọn một kiểu dữ liệu chỉ để chứa giá trị
record Order(int id, String customer, String item, int quantity) {
String toJson() {
return "{\"id\":%d,\"customer\":\"%s\",\"item\":\"%s\",\"quantity\":%d}"
.formatted(id, customer, item, quantity);
}
}
// Dữ liệu nằm trong bộ nhớ: tắt server là mất.
static final List<Order> orders = new ArrayList<>();
static int nextId = 3;
static final Pattern CUSTOMER = Pattern.compile("\"customer\"\\s*:\\s*\"([^\"]+)\"");
static final Pattern ITEM = Pattern.compile("\"item\"\\s*:\\s*\"([^\"]+)\"");
static final Pattern QUANTITY = Pattern.compile("\"quantity\"\\s*:\\s*(\\d+)");
public static void main(String[] args) throws IOException {
orders.add(new Order(1, "Lan", "Cà phê sữa", 2));
orders.add(new Order(2, "Hùng", "Bạc xỉu", 1));
HttpServer server = HttpServer.create(new InetSocketAddress(8080), 0);
server.createContext("/orders", OrderServer::handleOrders);
server.createContext("/getOrder", OrderServer::handleBadStyle);
server.start();
System.out.println("Server chạy tại http://localhost:8080");
}
// Kiểu đặt tên KHÔNG nên làm: động từ trong đường dẫn, lỗi nhưng vẫn trả 200.
static void handleBadStyle(HttpExchange ex) throws IOException {
send(ex, 200, "{\"error\":\"không tìm thấy đơn\"}");
}
static void handleOrders(HttpExchange ex) throws IOException {
String method = ex.getRequestMethod();
String[] parts = ex.getRequestURI().getPath().split("/"); // "/orders/1" -> ["", "orders", "1"]
if (parts.length == 2) { // /orders
switch (method) {
case "GET" -> send(ex, 200, listJson());
case "POST" -> createOrder(ex);
default -> methodNotAllowed(ex, "GET, POST");
}
} else if (parts.length == 3) { // /orders/{id}
int id;
try {
id = Integer.parseInt(parts[2]);
} catch (NumberFormatException e) {
send(ex, 400, "{\"error\":\"id phải là số\"}");
return;
}
switch (method) {
case "GET" -> getOrder(ex, id);
case "DELETE" -> deleteOrder(ex, id);
default -> methodNotAllowed(ex, "GET, DELETE");
}
} else {
send(ex, 404, "{\"error\":\"không có đường dẫn này\"}");
}
}
static String listJson() {
return "[" + String.join(",", orders.stream().map(Order::toJson).toList()) + "]";
}
static void getOrder(HttpExchange ex, int id) throws IOException {
for (Order o : orders) {
if (o.id() == id) {
send(ex, 200, o.toJson());
return;
}
}
send(ex, 404, "{\"error\":\"không tìm thấy đơn %d\"}".formatted(id));
}
static void createOrder(HttpExchange ex) throws IOException {
String body = new String(ex.getRequestBody().readAllBytes(), StandardCharsets.UTF_8);
Matcher customer = CUSTOMER.matcher(body);
Matcher item = ITEM.matcher(body);
Matcher quantity = QUANTITY.matcher(body);
if (!customer.find() || !item.find() || !quantity.find() || Integer.parseInt(quantity.group(1)) < 1) {
send(ex, 400, "{\"error\":\"cần customer, item và quantity (số nguyên từ 1)\"}");
return;
}
Order order = new Order(nextId++, customer.group(1), item.group(1), Integer.parseInt(quantity.group(1)));
orders.add(order);
ex.getResponseHeaders().set("Location", "/orders/" + order.id());
send(ex, 201, order.toJson());
}
static void deleteOrder(HttpExchange ex, int id) throws IOException {
if (orders.removeIf(o -> o.id() == id)) {
send(ex, 204, "");
} else {
send(ex, 404, "{\"error\":\"không tìm thấy đơn %d\"}".formatted(id));
}
}
static void methodNotAllowed(HttpExchange ex, String allowed) throws IOException {
ex.getResponseHeaders().set("Allow", allowed);
send(ex, 405, "{\"error\":\"phương thức không được hỗ trợ\"}");
}
static void send(HttpExchange ex, int status, String json) throws IOException {
ex.getResponseHeaders().set("Content-Type", "application/json; charset=utf-8");
if (status == 204) { // 204 không có nội dung
ex.sendResponseHeaders(204, -1);
ex.close();
return;
}
byte[] bytes = json.getBytes(StandardCharsets.UTF_8);
ex.sendResponseHeaders(status, bytes.length);
try (var out = ex.getResponseBody()) {
out.write(bytes);
}
}
}Đoạn code này khá dài, nhưng ý chính của nó chỉ có vài điểm. Hàm handleOrders đọc phương thức và đường dẫn của request, rồi chọn việc để làm: GET /orders trả danh sách, GET /orders/2 trả một đơn, POST /orders tạo đơn, DELETE /orders/2 xóa đơn. Hàm send ghép status code, header Content-Type và nội dung JSON thành response. Phần đọc JSON bằng biểu thức chính quy (regex) là cách làm thô sơ, chỉ để demo: nó sẽ hỏng với tên có dấu ngoặc kép. Spring Boot sẽ làm việc này bằng một thư viện chuyên dụng, và đó là một trong những lý do ta cần framework.
Bạn bật server bằng một dòng lệnh. Cờ -Dstdout.encoding=UTF-8 giúp chữ tiếng Việt in ra đúng trên Windows (mình đã nói lý do ở bài trước):
java -Dstdout.encoding=UTF-8 OrderServer.javaServer chạy tại http://localhost:8080Server đang chạy và chờ request. Hãy để cửa sổ này mở, và mở một cửa sổ dòng lệnh thứ hai để gọi nó.
Gọi từng phương thức và đọc mã trạng thái
Với mỗi lệnh dưới đây, mình dùng curl -si: cờ -i in cả header của response, cờ -s tắt thanh tiến trình cho đỡ rối. Bạn chỉ cần nhìn hai chỗ: dòng đầu tiên (có status code) và dòng cuối cùng (body).
Xem danh sách đơn, rồi một đơn cụ thể:
curl -si http://localhost:8080/orders
curl -si http://localhost:8080/orders/1HTTP/1.1 200 OK
Date: Mon, 16 Nov 2026 08:07:26 GMT
Content-type: application/json; charset=utf-8
Content-length: 126
[{"id":1,"customer":"Lan","item":"Cà phê sữa","quantity":2},{"id":2,"customer":"Hùng","item":"Bạc xỉu","quantity":1}]Status 200 và body là danh sách hai đơn của Lan và Hùng. Lệnh thứ hai cũng trả 200 với đơn số 1. Giờ hỏi một đơn không tồn tại:
curl -si http://localhost:8080/orders/99HTTP/1.1 404 Not Found
Date: Mon, 16 Nov 2026 08:07:26 GMT
Content-type: application/json; charset=utf-8
Content-length: 39
{"error":"không tìm thấy đơn 99"}Status là 404, cho client biết ngay "không có" mà không cần đọc chữ trong body. Tạo một đơn mới. Mình cho nội dung vào file don-moi.json (chữ tiếng Việt trong file này cần một lưu ý, mình nói ở phần sau):
{"customer":"Mai","item":"Trà đào","quantity":3}curl -si -X POST http://localhost:8080/orders -H "Content-Type: application/json" -d @don-moi.jsonHTTP/1.1 201 Created
Date: Mon, 16 Nov 2026 08:07:26 GMT
Content-type: application/json; charset=utf-8
Content-length: 58
Location: /orders/3
{"id":3,"customer":"Mai","item":"Trà đào","quantity":3}Có ba điều đáng nhìn. Status là 201 Created chứ không phải 200, vì đơn vừa được tạo. Header Location: /orders/3 cho client biết đường dẫn của đơn mới, để nó có thể gọi lại sau này. Và body trả về đơn vừa tạo, kèm id do server cấp. Giờ gửi một đơn thiếu quantity (file don-thieu.json chỉ có customer và item):
curl -si -X POST http://localhost:8080/orders -H "Content-Type: application/json" -d @don-thieu.jsonHTTP/1.1 400 Bad Request
Date: Mon, 16 Nov 2026 08:07:26 GMT
Content-type: application/json; charset=utf-8
Content-length: 67
{"error":"cần customer, item và quantity (số nguyên từ 1)"}400 Bad Request nghĩa là lỗi nằm ở request của client, nên server từ chối và nói rõ thiếu gì. Tiếp theo là xóa và một phương thức mà server không hỗ trợ:
curl -si -X DELETE http://localhost:8080/orders/1
curl -si -X PUT http://localhost:8080/orders/2 -H "Content-Type: application/json" -d @sua-don.jsonHTTP/1.1 204 No Content
Date: Mon, 16 Nov 2026 08:07:26 GMT
Content-type: application/json; charset=utf-8HTTP/1.1 405 Method Not Allowed
Date: Mon, 16 Nov 2026 08:07:26 GMT
Allow: GET, DELETE
Content-type: application/json; charset=utf-8
Content-length: 54
{"error":"phương thức không được hỗ trợ"}204 No Content nghĩa là xóa thành công và không có gì để trả về, nên response không có body. 405 thì cho biết đường dẫn /orders/2 có tồn tại nhưng không chấp nhận PUT, và header Allow liệt kê những phương thức được phép. Đây là cách một API tử tế nói chuyện: mỗi tình huống một mã riêng, client chỉ cần đọc con số.
Vì sao không nên đặt /getOrder và trả 200 cho mọi thứ?
Trong code, mình thêm một chỗ làm sai có chủ đích: đường dẫn /getOrder, vừa có động từ trong URL, vừa trả 200 cả khi báo lỗi. Gọi thử:
curl -si "http://localhost:8080/getOrder?id=99"HTTP/1.1 200 OK
Date: Mon, 16 Nov 2026 08:07:26 GMT
Content-type: application/json; charset=utf-8
Content-length: 36
{"error":"không tìm thấy đơn"}So sánh với GET /orders/99 ở trên: cùng là "không tìm thấy" nhưng một bên trả 404, một bên trả 200. Vì sao khác biệt này quan trọng? Vì mọi công cụ trên đường đi đều đọc status code để quyết định hành vi: ứng dụng điện thoại sẽ coi 200 là thành công và cố đọc quantity từ một body không có nó, trình giám sát đếm lỗi dựa vào các mã 4xx và 5xx sẽ không thấy lỗi nào, bộ nhớ đệm (cache) có thể giữ lại một "thành công" thật ra là lỗi. Gói lỗi trong body của một response 200 bắt mọi bên phải tự đọc và hiểu chữ, và đó là kiểu API mà đồng đội gọi là khó chịu. Mình sẽ quay lại chuyện trả lỗi cho thống nhất ở một bài sau, khi làm xử lý lỗi toàn cục trong Spring.
Vì sao chữ tiếng Việt bị vỡ khi gọi bằng curl trên Windows?
Lần đầu mình gõ chữ tiếng Việt thẳng vào dòng lệnh, kiểu -d '{"customer":"Mai","item":"Trà đào","quantity":3}', đơn tạo ra lưu tên món thành Tr� d�o. Server vẫn trả 201, nên nhìn bề ngoài không có lỗi, và dữ liệu sai nằm im trong bộ nhớ.
Nguyên nhân là giống hệt chuyện chữ vỡ ở bài trước. Trên Windows, curl.exe nhận tham số từ dòng lệnh theo bảng mã của hệ điều hành (Windows-1252), còn server đọc body theo UTF-8. Hai bên hiểu các byte khác nhau, và các chữ như à hay đ bị đọc sai. Cách tránh là đặt nội dung vào một file được lưu bằng UTF-8 và gửi bằng -d @tên-file, đúng như mình làm ở trên. Với mình, đây là bằng chứng nhỏ cho một nguyên tắc: dữ liệu đi qua ranh giới giữa hai hệ thống (dòng lệnh, mạng, file) là chỗ bảng mã hay hỏng nhất, nên luôn nói rõ bảng mã (ví dụ charset=utf-8 ở header Content-Type).
Gọi API bằng Postman thì làm thế nào?
curl tiện khi bạn muốn viết thành script, còn khi thử API hằng ngày, nhiều người thích một ứng dụng có giao diện như Postman hay Bruno. Cách dùng trong cả hai khá giống nhau: bạn chọn phương thức ở ô bên trái, dán đường dẫn vào ô bên cạnh, và bấm Send. Với POST, bạn mở thẻ Body, chọn dạng raw và kiểu JSON, rồi dán nội dung JSON; công cụ sẽ tự thêm header Content-Type: application/json. Kết quả hiện ở phần dưới, gồm status code, header và body.
Mình nói thẳng giới hạn ở đây: mình mô tả các bước này theo cách các công cụ đó làm việc nói chung, chứ không chụp màn hình từng bản, và vị trí các nút có thể khác giữa các phiên bản. Mọi kết quả trong bài này lấy từ curl mà mình đã chạy. Bạn làm một việc đơn giản để kiểm tra mình: gửi lại đúng các request ở trên bằng Postman, và so status code với bài.
Bước tiếp theo là gì?
Bạn đã nhìn thấy request và response, biết REST dùng đường dẫn, phương thức và status code ra sao, và có trong tay một API chạy được. Nhưng nó còn một điểm yếu lớn: dữ liệu nằm trong bộ nhớ. Mình thử tắt server rồi bật lại, và danh sách trả về chỉ còn đúng hai đơn ban đầu của Lan và Hùng. Đơn số 3 của Mai biến mất, còn đơn số 1 mà mình đã xóa lại xuất hiện như chưa từng bị động tới.
[{"id":1,"customer":"Lan","item":"Cà phê sữa","quantity":2},{"id":2,"customer":"Hùng","item":"Bạc xỉu","quantity":1}]Một quán cà phê không thể mất đơn mỗi lần máy chủ khởi động lại. Muốn lưu lâu dài, dữ liệu phải nằm trong một cơ sở dữ liệu, và muốn làm việc với nó bạn cần biết SQL. Đó là việc của các bài viết sau trong series Học Spring Boot: xây API đặt hàng từ con số 0.
Nếu bạn đang ôn phỏng vấn, thử trả lời câu REST khác HTTP ở điểm nào, và POST khác PUT ra sao trước khi đọc đáp án.