Hướng dẫn Cơ bản về Rest API
1. REST API là gì?
REST (Representational State Transfer) là một kiến trúc thiết kế API cho phép các ứng dụng client (Mobile App, Web App, Desktop App) giao tiếp với server thông qua HTTP protocol.
Đặc điểm chính:
Ví dụ:
Traditional Web App (Server-side rendering):
Browser → GET /products → Server renders HTML → Browser hiển thị
REST API (Client-side rendering):
Mobile App → GET /api/products → Server trả JSON → App render UI
Web App → GET /api/products → Server trả JSON → React/Vue render UI
2. Phân loại API Clients
App Backend API
Mục đích: Phục vụ ứng dụng của chính mình (Mobile App, SPA, Web App)
Đặc điểm:
Ví dụ:
Service API (Public/Third-party API)
Mục đích: Cung cấp dịch vụ cho bên thứ 3, nhiều apps khác nhau
Đặc điểm:
Ví dụ:
So sánh:
App Backend API
Service API
Ai dùng?
Chỉ app của bạn
Nhiều apps khác nhau
Authentication
JWT, Session
API Key, OAuth
Documentation
Nội bộ
Public, chi tiết
Versioning
Flexible
Strict (v1, v2…)
Breaking changes
OK nếu update app
Tuyệt đối tránh
3. Các loại dữ liệu API trả về
3.1. JSON (JavaScript Object Notation)
Ưu điểm:
Nhược điểm:
Ví dụ:
3.2. XML (eXtensible Markup Language)
Ưu điểm:
Nhược điểm:
Ví dụ:
Khi nào dùng XML:
3.3. HTML
Ưu điểm:
Nhược điểm:
Ví dụ (KHÔNG phải REST):
Lưu ý: Nếu API trả HTML → Đó là Server-Side Rendering, KHÔNG phải REST API!
3.4. Plain Text
Ưu điểm:
Nhược điểm:
Ví dụ:
Khi nào dùng Plain Text:
Chuẩn chung hiện nay: JSON
JSON là chuẩn de facto cho REST APIs vì:
Content-Type headers:
4. Các loại HTTP Methods
GET - Lấy dữ liệu
Đặc điểm:
POST - Tạo mới resource
Đặc điểm:
PUT - Thay thế toàn bộ resource
Đặc điểm:
PATCH - Update một phần resource
Đặc điểm:
PUT vs PATCH:
DELETE - Xóa resource
Đặc điểm:
OPTIONS - Kiểm tra methods được phép
OPTIONS method cho phép client hỏi server về:
Chính xác! Bạn hiểu đúng rồi. Để làm rõ hơn:
Lưu ý: OPTIONS Request là do Browser tự động gửi
Developer KHÔNG VIẾT CODE gửi OPTIONS - browser làm tự động!
OPTIONS to CORS Headers - Developer phải cấu hình
Developer phải cấu hình trên server để response OPTIONS request và các requests thật:
Flow hoàn chỉnh
Tóm tắt
Việc
Ai làm?
Khi nào?
Gửi OPTIONS request
Browser (tự động)
Cross-origin + (custom headers hoặc methods khác GET/POST)
Cấu hình CORS headers
Developer (phải code)
Setup server để response đúng CORS headers
Kiểm tra CORS policy
Browser (tự động)
Mỗi cross-origin request
Block/Allow request
Browser (tự động)
Dựa trên CORS headers từ server
Developer chỉ cần:
Ví dụ đơn giản nhất:
5. Cách đặt tên Endpoints (Best Practices)
✅ Đúng chuẩn REST
// Resources là danh từ số nhiều
GET /api/products // Lấy danh sách products
POST /api/products // Tạo product mới
GET /api/products/123 // Lấy product có id = 123
PUT /api/products/123 // Thay thế product 123
PATCH /api/products/123 // Update một phần product 123
DELETE /api/products/123 // Xóa product 123
// Nested resources
GET /api/users/456/orders // Orders của user 456
POST /api/users/456/orders // Tạo order cho user 456
GET /api/posts/789/comments // Comments của post 789
POST /api/posts/789/comments // Tạo comment cho post 789
// Actions/verbs chỉ khi thực sự cần
POST /api/auth/login
POST /api/auth/logout
POST /api/users/123/activate
POST /api/orders/456/cancel
POST /api/products/789/publish
❌ Sai chuẩn REST
// ❌ Dùng verbs trong URL
GET /api/getProducts
POST /api/createProduct
GET /api/deleteUser/123
// ✅ Đúng
GET /api/products
POST /api/products
DELETE /api/users/123
// ❌ Dùng số ít
GET /api/product/123
GET /api/user/456
// ✅ Đúng - luôn dùng số nhiều
GET /api/products/123
GET /api/users/456
URL Structure Best Practices
// Pattern: /api/{version}/{resource}/{id}/{sub-resource}
// Versioning
GET /api/v1/products
GET /api/v2/products // Breaking changes → new version
// Filtering
GET /api/products?category=phones&brand=apple
// Sorting
GET /api/products?sort=price_asc
GET /api/products?sort=-createdAt // "-" = descending
// Pagination
GET /api/products?page=2&limit=20
// Search
GET /api/products/search?q=iphone
// Fields selection
GET /api/products?fields=id,name,price
// Nested resources với limit
GET /api/users/123/posts?limit=5
6. Nguyên tắc của REST API (REST Principles)
1. Uniform Interface (Giao diện thống nhất)
Ý nghĩa: API endpoints phải rõ ràng, nhất quán, dễ dự đoán
Áp dụng:
Request/Response structure cũng phải consistent:
2. Stateless Interactions (Tương tác không trạng thái)
Ý nghĩa: Server KHÔNG lưu trạng thái của client, mỗi request phải chứa đủ thông tin
Ví dụ:
Lợi ích Stateless:
Implement:
3. Cacheable (Có thể cache)
Ý nghĩa: Server nên set cache headers để client/proxy có thể cache responses
Áp dụng:
Cache strategies:
4. Client-Server Separation
Ý nghĩa: Client và Server độc lập, giao tiếp chỉ qua API
Lợi ích:
Ví dụ:
5. Layered System (Hệ thống phân lớp)
Ý nghĩa: Client không cần biết có bao nhiêu layers giữa client và server
Ví dụ architecture:
Forward requests:
7. Response Status Code
// Success
200 OK - Request thành công (GET, PATCH, DELETE)
201 Created - Resource được tạo (POST)
204 No Content - Thành công nhưng không có data (DELETE)
// Client Errors
400 Bad Request - Request sai format
401 Unauthorized - Chưa đăng nhập
403 Forbidden - Đã login nhưng không có quyền
404 Not Found - Resource không tồn tại
422 Unprocessable - Validation failed
// Server Errors
500 Internal Server Error
503 Service Unavailable
Error Response Format
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Email is required",
"details": {
"field": "email",
"value": "",
"constraint": "required"
}
}
}
Complete Example
// routes/api/products.js
const router = require('express').Router();
// GET /api/products - List products
router.get('/', async (req, res) => {
try {
const { page = 1, limit = 20, category, sort } = req.query;
const products = await Product.findAll({
where: category ? { category } : {},
limit,
offset: (page - 1) * limit,
order: [[sort || 'createdAt', 'DESC']]
});
res.setHeader('Cache-Control', 'public, max-age=300');
res.json({
success: true,
data: products,
pagination: {
page: parseInt(page),
limit: parseInt(limit),
total: await Product.count()
}
});
} catch (error) {
res.status(500).json({
success: false,
error: {
code: 'INTERNAL_ERROR',
message: error.message
}
});
}
});
// POST /api/products - Create product
router.post('/', authenticateUser, async (req, res) => {
try {
const product = await Product.create(req.body);
res.status(201).json({
success: true,
data: product,
message: 'Product created successfully'
});
} catch (error) {
res.status(400).json({
success: false,
error: {
code: 'VALIDATION_ERROR',
message: error.message
}
});
}
});
module.exports = router;
REST API là nền tảng của modern web development - hiểu rõ principles và best practices sẽ giúp bạn xây dựng APIs scalable, maintainable, và developer-friendly!
