Knowledge Base›Knowledge Base›Tiêu chuẩn Phát triển API (API Standards)
Knowledge Base

Tiêu chuẩn Phát triển API (API Standards)

Cập nhật: 4 Tháng 1, 2026

Tài liệu này quy định các tiêu chuẩn bắt buộc khi phát triển và tích hợp API tại AMX.

1. Quy tắc đặt URL (Naming Convention)

1.1. Quy tắc vàng

  • Sử dụng Danh từ số nhiều cho tài nguyên (Resources).
  • Viết thường toàn bộ (lowercase).
  • Sử dụng gạch nối - (kebab-case) để phân cách từ, không dùng .
  • Không sử dụng động từ trong URL (CRUD được định nghĩa bởi HTTP Method).

Ví dụ:

✅ /api/v1/products

✅ /api/v1/user-profiles

❌ /api/v1/product (Số ít)

❌ /api/v1/getProducts (Dùng động từ)

❌ /api/v1/userprofiles (Dùng underscore)

1.2. Mẫu Endpoint tiêu chuẩn (Standard Patterns)

Tuân thủ nghiêm ngặt chuẩn RESTful:

| Hành động | HTTP Method | Endpoint | Mô tả |

| :--- | :--- | :--- | :--- |

| Danh sách | GET | /api/v1/resources | Lấy danh sách (có hỗ trợ filter, paging). |

| Chi tiết | GET | /api/v1/resources/{id} | Lấy chi tiết theo ID hoặc Slug. |

| Tạo mới | POST | /api/v1/resources | Tạo mới một resource. |

| Cập nhật | PUT | /api/v1/resources/{id} | Cập nhật thông tin resource. |

| Xóa | DELETE | /api/v1/resources/{id} | Xóa resource. |

Action mở rộng (Sub-resources):

  • /api/v1/products/categories (Danh mục sản phẩm)
  • /api/v1/products/search (Tìm kiếm - Alias của List nhưng rõ nghĩa hơn cho việc filter)
  • /api/v1/users/{id}/change-password (Hành động cụ thể)
[!TIP]
Search Routes: Đối với các tài nguyên có nhiều bộ lọc (filters), nên cung cấp thêm route /search trỏ về cùng method index hoặc search để client dễ dàng phân biệt hành động "Get List" và "Search".
VD: GET /api/v1/projects (List default) và GET /api/v1/projects/search?q=abc (Search).

1.4. Tổ chức Routes (Route Organization)

Để đảm bảo code gọn gàng và dễ quản lý, BẮT BUỘC sử dụng group() cho các resource.

Quy tắc:

  • Gom nhóm các routes cùng resource lại với nhau.
  • Áp dụng Middleware/Filter ở cấp Group (không lặp lại ở từng route con).
  • Group name nên trúng với tên resource (số nhiều).

Ví dụ Chuẩn:

// ✅ Đúng
$routes->group('products', ['filter' => 'apiauth'], function ($routes) {
    $routes->get('', 'ProductController::index');       // GET /products
    $routes->get('(:num)', 'ProductController::show/$1'); // GET /products/123
});

Ví dụ Sai:

// ❌ Sai (Lặp lại, khó quản lý)
$routes->get('products', 'Product::index', ['filter' => 'apiauth']);
$routes->get('products/(:num)', 'Product::show/$1', ['filter' => 'apiauth']);

1.5. Versioning (Bắt buộc)

Luôn luôn có prefix version trong URL.

  • Hiện tại: /api/v1/...

2. Chuẩn phản hồi (Response Format)

Mọi API phải trả về dữ liệu kiểu JSON (application/json) theo cấu trúc thống nhất.

2.1. Phản hồi Thành công (Success)

HTTP Code: 200 OK hoặc 201 Created

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Iphone 15"
  },
  "message": "Thao tác thành công" // Optional
}

2.2. Phản hồi Lỗi (Error)

HTTP Code: 400, 401, 403, 404, 500...

{
  "success": false,
  "message": "Mô tả lỗi chi tiết dành cho Developer/Client",
  "errors": { // Optional: Chi tiết lỗi validation
    "email": "Email không hợp lệ",
    "password": "Mật khẩu quá ngắn"
  }
}

2.3. Lite Response (Tối ưu hóa)

Để đảm bảo hiệu năng cho Mobile App và danh sách dài:

  • API List (GET /resources):
- ❌ KHÔNG trả về các trường nội dung lớn (HTML content, Base64 images).

- ✅ CHỈ trả về thông tin tóm tắt: id, name, slug, thumbnail, description (ngắn), price, createdat.

  • API Detail (GET /resources/{id}): Trả về đầy đủ thông tin.

3. Redis Cache Convention

Hệ thống sử dụng Redis làm caching layer chính. Việc đặt tên Key phải tuân thủ quy tắc để dễ dàng quản lý và xóa cache theo nhóm (Bulk Clear).

Format Key:

apiv1{resource}{action}{tenantid}{uniqueidentifier}

Giải thích:

  • apiv1: Prefix cố định (Dùng thay vì : để tương thích tốt nhất với CI4 Cache Driver).
  • {resource}: Tên tài nguyên số nhiều (e.g., products, news).
  • {action}: Hành động (e.g., list, detail, search, categories).
  • {tenantid}: ID của Tenant hiện tại (Quan trọng cho Multi-tenancy).
  • {uniqueidentifier}: Các tham số định danh duy nhất (Page, Limit, ID, Slug, Search Query...).

Ví dụ thực tế:

  • Danh sách sản phẩm (Tenant 1, Page 1, Limit 10):
apiv1productslist1page1limit10
  • Chi tiết tin tức (Tenant 2, Slug 'tin-moi'):
apiv1newsdetail2slugtin-moi
  • Tìm kiếm (Tenant 1, Query 'iphone'):
apiv1productssearch1q_iphone

Thời gian Cache (TTL):

  • Dữ liệu tĩnh/ít thay đổi (List, Detail): 600s (10 phút).
  • Cấu hình hệ thống (Settings): 3600s (1 giờ).
  • Dữ liệu Real-time (Kho, Giá nhảy): 60s (1 phút).
MessengerChat ZaloZaloHotline: 0938809000