Skip to content

Quy ước API ​

Trang này nói về những quy ước chung khi frontend gọi backend: địa chỉ, dạng phản hồi, cách khai báo endpoint mới và cách đặt tên hook. Dành cho người định thêm hoặc sửa một endpoint.

Vì sao cần quy ước chung ​

Có hơn 70 endpoint trải trên 12 file. Nếu mỗi file tự quyết định cách nối URL, cách gửi tham số hay cách đọc phản hồi thì rất khó sửa lỗi chung, chẳng hạn như thêm header hoặc xử lý 401. Vì vậy mọi endpoint đi qua cùng một baseApi, một baseQuery và một Axios instance.

WARNING

Địa chỉ backend được viết cứng trong code là http://localhost:8081/api/v1, không đọc từ biến môi trường. Đổi môi trường nghĩa là phải sửa file constant.ts. Xem Biến môi trường.

Đường đi của một request ​

Interceptor của Axios trả về response.data, nên data mà hook nhận chính là thân phản hồi ApiResponse, không phải đối tượng response của Axios.

Các quy ước ​

Hạng mụcQuy ước trong code
Địa chỉAPI_BASE_URL trong src/shared/constants/constant.ts
Nối URLaxiosBaseQuery nối baseUrl + url thành URL tuyệt đối
Timeout10 giây (axios.create)
CookiewithCredentials: true, để gửi cookie refresh token
Xác thựcHeader Authorization: Bearer <access_token> lấy từ localStorage, gắn ở request interceptor
Content-Typeapplication/json, trừ khi data là FormData
Upload fileGửi FormData, không đặt Content-Type thủ công
Cache tagKhai báo trong tagTypes của baseApi

Cơ chế làm mới token khi gặp 401 nằm ở Xác thực.

Dạng phản hồi ​

ApiResponse<T> được định nghĩa ở src/shared/base/api-response.base.ts:

FieldKiểuBắt buộcÝ nghĩa
statusCodenumber | stringCóMã trạng thái backend ghi trong thân phản hồi
messagestring | nullCóThông điệp từ backend, có thể null
dataTKhôngDữ liệu chính
timestampstring | nullKhôngThời điểm phản hồi
errorstring | string[]KhôngThông tin lỗi nếu có

Danh sách phân trang có dạng PaginatedResult<T>, xem Phân trang và lọc.

Thêm một endpoint ​

  1. Nếu nhóm API chưa có, tạo src/features/<tên>/redux/<tên>.api.ts và gọi baseApi.injectEndpoints.
  2. Khai báo builder.query cho thao tác đọc hoặc builder.mutation cho thao tác ghi, ghi rõ kiểu ApiResponse<...>.
  3. Thao tác đọc dùng providesTags, thao tác ghi dùng invalidatesTags. Tag mới phải được thêm vào tagTypes trong src/lib/redux/api.ts.
  4. Export hook do RTK Query sinh ra.
  5. Nếu logic phức tạp (toast, đóng dialog), bọc trong một hook ở src/hooks/.
ts
// src/features/job/redux/job.api.ts (rút gọn)
export const jobApi = baseApi.injectEndpoints({
  endpoints: (builder) => ({
    getJob: builder.query<ApiResponse<Job>, string>({
      query: (id) => ({ url: `/jobs/${id}`, method: "GET" }),
      providesTags: (result, error, id) => [{ type: "Job", id }],
    }),
  }),
});

Đặt tên ​

Thành phầnQuy ướcVí dụ
EndpointĐộng từ + danh từ, camelCasegetJob, createJob, bulkDeleteJobs
Hook đọcuse<Endpoint>QueryuseGetJobQuery
Hook ghiuse<Endpoint>MutationuseCreateJobMutation
Schema form<Tên>FormData trong schemas/CreateJobFormData

Cách dựng tham số ​

Code không dùng một cách duy nhất. Có hai kiểu đang tồn tại cạnh nhau:

KiểuVí dụGhi chú
Tự nối chuỗi querygetJobs dựng page=..&limit=.. rồi nối filter và sortDùng cho các danh sách quản trị theo kiểu lọc của backend
Truyền params cho AxiossearchJobs truyền đối tượng JobSearchParamsAxios tự mã hóa query string

Source code liên quan ​

Backend mô tả định dạng phản hồi và lỗi ở Tổng quan API của backend.

Đọc tiếp: Xử lý lỗi, Phân trang và lọc, Cache và invalidation.

Tài liệu kỹ thuật xây dựng theo chuẩn Documentation as Code