REST API là gì? Hướng dẫn đầy đủ cho lập trình viên

APIs là nền tảng của web hiện đại. Mỗi khi bạn kiểm tra thời tiết trên điện thoại, lướt mạng xã hội, hay thanh toán online, bạn đang sử dụng APIs. Trong số các kiến trúc API, REST đã trở thành tiêu chuẩn de facto cho web services.

Trong hướng dẫn toàn diện này, bạn sẽ học mọi thứ cần biết về REST APIs—từ khái niệm cơ bản đến các patterns nâng cao được sử dụng trong production.

Bạn sẽ học được gì

✅ API là gì và tại sao chúng quan trọng
✅ Nguyên tắc kiến trúc REST và các ràng buộc
✅ HTTP methods và khi nào sử dụng từng loại
✅ Status codes và ý nghĩa của chúng
✅ Thiết kế URL và quy ước đặt tên resource
✅ Các phương pháp authentication và authorization
✅ Chiến lược versioning, pagination và filtering
✅ Best practices để xây dựng REST APIs chất lượng

Phần 1: Hiểu về API

API là gì?

API là viết tắt của Application Programming Interface. Đó là một hợp đồng định nghĩa cách hai ứng dụng phần mềm giao tiếp với nhau.

Hãy tưởng tượng API như menu nhà hàng:

• Bạn (client): Muốn gọi món
• Menu (API): Cho thấy những gì có sẵn và cách gọi
• Bếp (server): Chuẩn bị và giao những gì bạn gọi
• Phục vụ (API request/response): Mang đơn hàng và trả về món ăn

┌─────────────┐                      ┌─────────────┐
│   Client    │  ──── Request ────▶  │   Server    │
│  (App)      │                      │  (Backend)  │
│             │  ◀─── Response ────  │             │
└─────────────┘                      └─────────────┘

Các loại API

REST thống trị web APIs vì sự đơn giản và phổ biến của nó.

Phần 2: REST Cơ bản

REST là gì?

REST là viết tắt của Representational State Transfer. Được giới thiệu bởi Roy Fielding trong luận án tiến sĩ năm 2000.

REST không phải là protocol hay standard—nó là một architectural style với tập hợp các ràng buộc mà khi tuân theo, tạo ra web services có khả năng mở rộng và dễ bảo trì.

Sáu ràng buộc REST

1. Client-Server

Client và server là các mối quan tâm riêng biệt:

• Client: Xử lý giao diện người dùng
• Server: Xử lý lưu trữ dữ liệu, logic nghiệp vụ và bảo mật

2. Stateless

Mỗi request phải chứa tất cả thông tin cần thiết để xử lý nó. Server không lưu trữ trạng thái client giữa các requests.

// ❌ Stateful (server nhớ user)
GET /api/cart  // Server: "User nào? Tôi cần check session..."
 
// ✅ Stateless (request chứa mọi thứ)
GET /api/users/123/cart
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

3. Cacheable

Responses phải chỉ định liệu chúng có thể được cache không.

4. Uniform Interface

REST APIs phải có giao diện nhất quán, có thể dự đoán được:

• Sử dụng URIs để định danh resources
• Sử dụng HTTP methods (GET, POST, PUT, DELETE)
• Messages tự mô tả với headers
• HATEOAS (links đến resources liên quan)

5. Layered System

Clients không thể biết họ đang kết nối trực tiếp với server hay qua các trung gian (load balancers, caches, proxies).

6. Code on Demand (Tùy chọn)

Servers có thể gửi code thực thi cho clients (JavaScript). Ràng buộc tùy chọn duy nhất.

Resources: Trái tim của REST

Trong REST, mọi thứ là một resource. Mỗi resource có:

• Một định danh duy nhất (URI)
• Một hoặc nhiều representations (JSON, XML, HTML)

Resource: User #123
URI: /api/users/123
Representation (JSON):
{
  "id": 123,
  "name": "John Doe",
  "email": "[email protected]"
}

Phần 3: HTTP Methods

HTTP methods định nghĩa hành động nào thực hiện trên resource.

CRUD Mapping

GET - Lấy Resources

GET /api/users/123 HTTP/1.1
 
HTTP/1.1 200 OK
{
  "id": 123,
  "name": "John Doe",
  "email": "[email protected]"
}

Đặc điểm: Safe (không thay đổi data), Idempotent (cùng request = cùng result), Cacheable

POST - Tạo Resources

POST /api/users HTTP/1.1
Content-Type: application/json
 
{
  "name": "Jane Doe",
  "email": "[email protected]"
}
 
HTTP/1.1 201 Created
Location: /api/users/124

Đặc điểm: Không safe, Không idempotent (mỗi call tạo resource mới)

PUT vs PATCH

DELETE - Xóa Resources

DELETE /api/users/123 HTTP/1.1
 
HTTP/1.1 204 No Content

Tóm tắt Safety và Idempotency

Phần 4: HTTP Status Codes

2xx - Thành công

4xx - Lỗi Client

5xx - Lỗi Server

Phần 5: Thiết kế URL

Quy ước đặt tên Resource

1. Dùng Danh từ, không dùng Động từ

✅ Tốt
GET /users
POST /orders
 
❌ Xấu
GET /getUsers
POST /createOrder

2. Dùng Danh từ số nhiều

✅ /users
✅ /users/123
✅ /products

3. Dùng Dấu gạch ngang cho Multi-Word

✅ /user-profiles
✅ /order-items

4. Biểu diễn quan hệ với Nesting

GET /users/123/orders        # Orders của user
GET /orders/456/items        # Items của order

Query Parameters

# Filtering
GET /products?category=electronics&price_min=100
 
# Sorting
GET /products?sort=-price    # Giảm dần (prefix -)
 
# Pagination
GET /products?page=2&limit=20
 
# Field selection
GET /users?fields=id,name,email

Phần 6: Request và Response Bodies

Cấu trúc Response

Single Resource

{
  "id": 123,
  "name": "John Doe",
  "email": "[email protected]",
  "createdAt": "2024-01-20T14:30:00Z"
}

Collection với Metadata

{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 10,
    "totalPages": 15
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation thất bại",
    "details": [
      {"field": "email", "message": "Email không hợp lệ"}
    ]
  }
}

Phần 7: Authentication

1. API Keys

GET /api/data HTTP/1.1
X-API-Key: sk_live_abc123xyz

Ưu điểm: Đơn giản Nhược điểm: Không có ngữ cảnh user

2. JWT (JSON Web Tokens)

GET /api/users/me HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

// Payload đã decode
{
  "sub": "user_123",
  "name": "John Doe",
  "role": "admin",
  "exp": 1516325422
}

Ưu điểm: Stateless, chứa thông tin user, scalable Nhược điểm: Khó thu hồi, overhead kích thước

3. OAuth 2.0

Cho truy cập bên thứ ba và social logins.

Phần 8: Versioning

URL Path Versioning (Khuyến nghị)

GET /api/v1/users
GET /api/v2/users

Ưu điểm: Rõ ràng và explicit, dễ route, cacheable

Best Practices

1. Bắt đầu với v1, ngay cả khi nghĩ không cần versions
2. Version toàn bộ API, không phải từng endpoints
3. Ghi chú timeline deprecation
4. Cung cấp migration guides

Phần 9: Pagination

Offset-Based

GET /api/users?page=2&limit=20

Ưu điểm: Đơn giản, có thể nhảy đến bất kỳ trang nào Nhược điểm: Không nhất quán với real-time data

Cursor-Based

GET /api/users?cursor=eyJpZCI6MTIzfQ&limit=20

Ưu điểm: Kết quả nhất quán, xử lý real-time data, hiệu quả Nhược điểm: Không thể nhảy đến trang cụ thể

Phần 10: REST API Best Practices

1. Dùng HTTP Methods đúng

✅ GET để đọc
✅ POST để tạo
✅ PUT/PATCH để cập nhật
✅ DELETE để xóa

2. Trả về Status Codes phù hợp

✅ 200 cho GET/PUT/PATCH thành công
✅ 201 cho POST thành công (creation)
✅ 204 cho DELETE thành công
✅ 4xx cho lỗi client
✅ 5xx cho lỗi server

3. Version API từ đầu

✅ /api/v1/users

4. Dùng HTTPS luôn luôn

✅ https://api.example.com
❌ http://api.example.com

5. Implement Rate Limiting

HTTP/1.1 429 Too Many Requests
Retry-After: 60

6. Document API

Sử dụng OpenAPI/Swagger cho documentation.

Phần 11: REST vs Alternatives

REST vs GraphQL

Dùng REST khi: CRUD operations, simple data, caching quan trọng Dùng GraphQL khi: Complex data relationships, mobile apps

REST vs gRPC

Dùng REST khi: Public APIs, browser clients, đơn giản Dùng gRPC khi: Microservices, high-performance

Tóm tắt

REST APIs là xương sống của phát triển web hiện đại:

Checklist Best Practices

✅ Dùng danh từ cho resources, không dùng động từ
✅ Dùng HTTP methods và status codes đúng
✅ Version API từ ngày đầu
✅ Implement authentication (JWT, OAuth)
✅ Dùng HTTPS everywhere
✅ Paginate large collections
✅ Document với OpenAPI/Swagger
✅ Trả về error responses nhất quán
✅ Implement rate limiting
✅ Bao gồm request IDs để debugging

Tiếp theo

Xây dựng REST APIs:

• Bắt đầu với Spring Boot - Xây dựng REST APIs với Java
• Spring Boot REST API Best Practices - Patterns nâng cao với Java
• TypeScript Phase 3: Backend Development - REST APIs với Node.js
• Bắt đầu với FastAPI - REST APIs với Python

Tài liệu hóa APIs:

• API Documentation với OpenAPI/Swagger - Tự động tạo tài liệu tương tác
• Hiểu OpenAPI với FastAPI - OpenAPI trong Python

Tìm hiểu sâu:

• HTTP Protocol Complete Guide - Deep dive về HTTP
• Database Schema Design - Thiết kế data layer

REST APIs có vẻ đơn giản trên bề mặt, nhưng thành thạo chúng đòi hỏi hiểu HTTP, thiết kế resource, và nhiều best practices tinh tế. Với nền tảng này, bạn đã sẵn sàng xây dựng APIs mạnh mẽ, có khả năng mở rộng mà developers thích sử dụng.

Chúc bạn xây dựng API vui vẻ! 🚀