10 lưu ý để thiết kế API đúng

Th8 19, 2023 | Bài viết chuyên môn, Blog | 0 Lời bình

RESTful API (hay REST API) là một giao diện lập trình ứng dụng (API hay web API) tuân theo các ràng buộc của kiểu kiến trúc REST, cho phép tương tác với các dịch vụ web RESTful.

Hay nói đơn giản, RESTful API là một tiêu chuẩn được dùng trong việc thiết kế API dành cho các ứng dụng web (thiết kế Web Services) để hỗ trợ cho việc quản lý các resource.

REST là viết tắt của cụm từ Representational state transfer (ứng dụng chuyển đổi cấu trúc dữ liệu)

Hôm nay chúng ta sẽ luyện tập thiết kế Rest API dựa trên một số ví dụ các bạn nhé!

1. SỬ DỤNG DANH TỪ ĐỂ XÁC ĐỊNH TÀI NGUYÊN

Khái niệm cơ bản của hệ thống dựa trên REST là tài nguyên (resource). Một tài nguyên có thể là bất cứ điều gì bạn muốn hiển thị

Ví dụ: Tài nguyên cho hệ thống quản lý nhân viên:

– Employee

– Department

– Projects

– Task

– Address

Định nghĩa các URI:

GET – /users – Trả về danh sách users

GET – users/100 – Trả về một user cụ thể

POST – /users – Tạo mới một user

PUT – /users/5 – Cập nhật một user cụ thể

DELETE – /users/711 – Xóa một user

Không được định nghĩa các URI như sau:

/getAllUsers

/getUserById

/createNewUser

/updateUser

/deleteUser

2. SỬ DỤNG DANH TỪ SỐ NHIỀU

Dùng /students thay vì /student

Dùng /employees thay vì /employee

Dùng /orders thay vì /order

Dùng /users thay vì /user

Dùng /customers thay vì /customer

3. SỬ DỤNG CÁC HEADER HTTP ĐÚNG CHO ĐỊNH DẠNG TUẦN TỰ HÓA DỮ LIỆU

Cả client và server cần biết định dạng để giao tiếp với nhau. Định dạng này cần phải được chỉ rõ trong HTTP-Header

Content-Type: xác định định dạng của request gửi lên. Có các loại content-type phổ biến sau: “text/plain”, “application/xml”, “text/html”, “application/json”, “image/gif”, and “image/jpeg”.

Accept: định nghĩa các định dạng trả về, các loại accept tương tự content-type

Ví dụ:

Content-Type: application/json

Accept: application/json

4. PHƯƠNG THỨC GET VÀ THAM SỐ TRUY VẤN KHÔNG NÊN THAY ĐỔI TRẠNG THÁI

Hãy sử dụng các phương thức PUT, POST và DELETE thay thế cho phương thức GET để thay đổi trạng thái. Không sử dụng phương thức GET để thay đổi trạng thái:

Ví dụ:

GET /users/711?activate

Hoặc: GET /users/711/activate

5. SỬ DỤNG CÁC TÀI NGUYÊN CON ĐỂ ĐẠI DIỆN CÁC MỐI QUAN HỆ

Nếu một mối quan hệ chỉ tồn tại bên trong một tài nguyên khác, các nguyên tắc RESTful cung cấp hướng dẫn hữu ích.

Trong REST, mối quan hệ thường được mô hình hóa bằng tài nguyên con. Sử dụng mẫu sau đây cho các tài nguyên con.

GET /{resource}/{resource-id}/{sub-resource}

GET /{resource}/{resource-id}/{sub-resource}/{sub-resource-id}

POST /{resource}/{resource-id}/{sub-resource}

Ví dụ:

GET /{post}/{post-id}/{comments}

GET /{post}/{post-id}/{comments}/{comment-id}

POST /{post}/{post-id}/{comments}

Sử dụng tài nguyên con khi một đối tượng con không thể tồn tại mà không có đối tượng cha.

Một số ví dụ khác về tài nguyên con:

GET /cars/711/drivers/ – Trả về danh sách các tài xế cho xe 711

GET /cars/711/drivers/4 – Trả về tài xế số 4 cho xe 711

Những yêu cầu này có thể được ánh xạ logic đến /tickets như sau:

GET /tickets/12/messages – Lấy danh sách các tin nhắn cho vé số 12

GET /tickets/12/messages/5 – Lấy tin nhắn số 5 cho vé số 12

POST /tickets/12/messages – Tạo một tin nhắn mới trong vé số 12

PUT /tickets/12/messages/5 – Cập nhật tin nhắn số 5 trong vé số 12

PATCH /tickets/12/messages/5 – Cập nhật một phần tin nhắn số 5 trong vé số 12

DELETE /tickets/12/messages/5 – Xóa tin nhắn số 5 trong vé số 12

6. SỬ DỤNG PHƯƠNG THỨC HTTP METHOD THÍCH HỢP

GET: Lấy thông tin từ một tài nguyên đã tồn tại trên máy chủ. Phương thức này thường được sử dụng để yêu cầu dữ liệu từ máy chủ, và không thay đổi trạng thái của tài nguyên.

POST: Tạo mới một tài nguyên trên máy chủ. Phương thức này được sử dụng để gửi dữ liệu từ client lên máy chủ để tạo một tài nguyên mới. Ví dụ, khi bạn điền một biểu mẫu trên trang web và nhấn nút “Submit,” thông tin sẽ được gửi lên server bằng phương thức POST để tạo mới một bài đăng, bình luận, hoặc người dùng mới.

PUT: Cập nhật hoặc thay đổi thông tin của một tài nguyên tồn tại trên máy chủ. Phương thức này được sử dụng để ghi đè lên thông tin hiện có của tài nguyên bằng dữ liệu mới được gửi lên từ client. Lưu ý rằng, nếu tài nguyên không tồn tại, PUT sẽ tạo một tài nguyên mới với thông tin cung cấp.

PATCH: Tương tự như PUT, nhưng PATCH chỉ cập nhật một phần của tài nguyên thay vì ghi đè lên toàn bộ tài nguyên. Nó cho phép bạn gửi một yêu cầu chỉ để cập nhật một số trường hoặc thuộc tính cụ thể của tài nguyên.

DELETE: Xóa một tài nguyên trên máy chủ. Phương thức này được sử dụng để yêu cầu xóa bỏ một tài nguyên cụ thể trên máy chủ.

7. MÃ PHẢN HỒI TRẠNG THÁI HTTP

200 OK: Mã này cho biết rằng yêu cầu đã thành công và nội dung phản hồi được trả về cho client theo yêu cầu.

201 Created: Yêu cầu đã được xử lý thành công và đã tạo một tài nguyên mới như yêu cầu.

400 Bad Request: Yêu cầu của client không hợp lệ hoặc không thể hiểu được bởi máy chủ. Điều này có thể xảy ra nếu dữ liệu không hợp lệ hoặc các tham số bị thiếu.

401 Unauthorized: Yêu cầu yêu cầu xác thực, và client không được ủy quyền để thực hiện yêu cầu này. Client cần cung cấp thông tin đăng nhập hợp lệ để truy cập tài nguyên.

403 Forbidden: Yêu cầu hợp lệ, nhưng máy chủ từ chối cung cấp tài nguyên. Điều này có thể xảy ra khi client không có quyền truy cập vào tài nguyên.

404 Not Found: Tài nguyên được yêu cầu không tồn tại trên máy chủ.

500 Internal Server Error: Máy chủ gặp phải một lỗi không xác định trong quá trình xử lý yêu cầu. Điều này thường xảy ra khi có lỗi bên trong máy chủ.

8. QUY ƯỚC VIẾT TÊN TRƯỜNG (Field Name Casing Convention)

Bạn có thể tuân theo bất kỳ quy ước viết nào, nhưng hãy đảm bảo nó được nhất quán trong toàn ứng dụng. Nếu thân thiện yêu cầu hoặc loại phản hồi là JSON thì hãy tuân theo quy ước camelCase để duy trì tính nhất quán.

Ví dụ dưới đây sử dụng camelCase làm tên trường trong JSON:

json

Copy code

{

“firstName”: “Ramesh”,

“lastName”: “Fadatare”,

“id”: 100,

“userName”: “Ramesh Fadatare”,

“email”: “ramesh@gmail.com”

}

Trong đó:

firstName: Tên của người dùng.

lastName: Họ của người dùng.

id: Mã số duy nhất của người dùng.

userName: Tên người dùng kết hợp giữa tên và họ.

email: Địa chỉ email của người dùng.

Việc tuân theo quy ước camelCase giúp đảm bảo tính nhất quán trong việc đặt tên trường và dễ đọc, cải thiện khả năng hiểu và bảo trì mã nguồn trong ứng dụng.

9. TÌM KIẾM, SẮP XẾP, LỌC VÀ PHÂN TRANG

Đối với tìm kiếm, sắp xếp, lọc và phân trang, không cần tạo một REST API mới, bạn có thể hỗ trợ những thao tác này trong REST API GET hiện tại bằng cách thêm các tham số truy vấn vào địa chỉ GET.

Ví dụ:

Sắp xếp – Trong trường hợp client muốn nhận danh sách công ty được sắp xếp, endpoint GET /companies sẽ chấp nhận nhiều tham số sắp xếp trong truy vấn. Ví dụ GET /companies?sort=rank_asc sẽ sắp xếp danh sách công ty theo thứ tự tăng dần của hạng.

Nếu nhiều tiêu chí: /companies?sort=rank_desc,name_asc

Lọc – Để lọc dữ liệu, chúng ta có thể truyền các tùy chọn khác nhau thông qua tham số truy vấn. Ví dụ GET /companies?category=banking&location=india sẽ lọc dữ liệu danh sách công ty với danh mục công ty là “Banking” và địa điểm là “India”.

Tìm kiếm – Khi tìm kiếm tên công ty trong danh sách công ty, API endpoint sẽ là GET /companies?search=Digital.

Phân trang – Khi dữ liệu quá lớn, chúng ta chia dữ liệu thành các phần nhỏ, giúp cải thiện hiệu suất và dễ xử lý phản hồi. Ví dụ GET /companies?page=23 có nghĩa là lấy danh sách công ty trên trang thứ 23.

10. PHIÊN BẢN HÓA API RESTFUL

Phiên bản hóa API Restful là việc quản lý các thay đổi trong API của bạn một cách minh bạch.

Dưới đây là 4 cách để đánh phiên bản một REST API: