Tìm hiểu về index trong database

An API is a user interface for developers. Put the necessary effort in it to ensure it’s not just functional but pleasant to use.

Bài viết này sẽ nói về phương pháp thiết kế RestFul API, cũng như các lỗi thường gặp phải khi thiết kế chúng.

Tìm hiểu về HTTP Method

Các HTTP Method thường sẽ có 2 loại là SAFE và IDEMPOTENT.

• SAFE: không làm thay đổi state của server, tức là nó sẽ đọc và không làm thay đổi dữ liệu. Các method SAFE gồm: GET, HEAD, OPTIONS. Các method UNSAFE gồm PUT, DELETE, POST, PATCH.
• IDEMPOTENT: các method loại này có thể thực hiện n + 1 lần mà vẫn trả lại kết quả ban đầu. Vì vậy các method SAFE sẽ luôn IDEMPOTENT, còn UNSAFE thì chưa chắc

Các loại HTTP Method

HTTP method là các phương thức mà một máy chủ web và một trình duyệt web sử dụng để giao tiếp và thực hiện các hành động trên các tài nguyên web. Các HTTP method quan trọng nhất bao gồm:

• GET: lấy resource từ server theo URI.
• HEAD: cũng giống như GET, nhưng response trả về không có body, chỉ có header.
• POST: gửi resource tới server thông qua các form, thường dùng cho mục đích tạo mới resource.
• PUT: cập nhật tất cả thông tin của đối tượng với những thông tin được gửi lên.
• PATCH: chỉ cập nhật các thông tin được thay đổi của đối tượng.
• DELETE: xóa resource trên server.
• CONNECT: thiết lập một kết nối tới server theo URI.
• OPTIONS: mô tả các tùy chọn giao tiếp cho reource.
• TRACE: thực hiện 1 bài test loop-back theo đường dẫn tới resource.

So sánh các HTTP Method

• GET với POST: có một câu hỏi là: GET có thể được dùng để đẩy dữ liệu lên hay POST có thể được dùng để lấy dữ liệu về hay không?, câu trả lời là có. Nhưng chúng ta sẽ không làm như vậy, nó sẽ vi phạm các quy tắc về thiết kế API. GET sẽ không có body, cho nên khi dùng GET để truyền dữ liệu lên server ta sẽ thấy các parameters đều hiển thị trên URL, nó sẽ thiếu bảo mật. Còn POST sẽ giấu parameters trong body và được mã háo khi truyền lên, nhưng nó chỉ an toàn với phía Client, còn với Server thì khác, tức là ta có thể đứng từ Server và nhìn thấy nội dung được truyền lên.
• POST, PUT và PATCH: PUT là IDEMPOTENT còn POST thì không, bạn sẽ nhận được lỗi khi gửi 1 request POST với cùng nội dung 2 lần, nguyên nhân có thể là trùng lặp dữ liệu, hoặc do trạng thái tài nguyên, còn với PUT thì sẽ luôn trả về kết quả giống nhau. PATCH khác với PUT ở chỗ là nó sẽ cập nhật 1 phần của resource thay vì cập nhật lại hết như PUT.

Thiết kế Restful API

Một số nguyên tắc

• Giữ nó đơn giản: Hãy thiết kế URL của 1 API một cách đơn giản, ví dụ khi ta muốn tạo API cho các sản phẩm, thì nó nên là:

/products                 // lấy tất cả sản phẩm
/products/{productID}     // lấy chi tiết sản phẩm theo ID

• Sử dụng danh từ thay vì động từ: Đây là lỗi thường hay gặp phải khi thiết kế API, ví dụ:

/getAllProducts           // sai
/products                // đúng

• Sử dụng số nhiều: sử dụng số nhiều sẽ tránh nhầm lẫn về việc ta đang lấy một resource hay collection resource từ server, nó cũng tránh thêm những thứ bổ sung vào URL như:

/product/all             // không cần thiết
/product                    
/products                // nên dùng như này

• Sử dụng các tham số: nên sử dụng dạng query parameters trong các trường hợp muốn lọc dữ liệu theo các điều kiện

/products?name='ABC'     // thay vì sử dụng getProductsByName
/products?type='XYZ'    // thay vì sử dụng getProductsByType

• Sử dụng các HTTP Method một cách hợp lý: Một số HTTP Method thường được sử dụng là:

  • GET: lấy tài nguyên
  • POST: thêm mới tài nguyên
  • PUT/PATCH: cập nhật tài nguyên
  • DELETE: xóa tài nguyên

• Sử dụng HTTP codes thích hợp: các HTTP codes thường sử dụng nằm trong khoảng 200-500, bao gồm:

  • 200 OK: được sử dụng phổ biến nhất khi thực hiện gọi API thành công.
  • 201 CREATED: được sử dụng khi sử dụng POST để thêm mới tài nguyên.
  • 202 ACCEPTED: được sử dụng để xác nhận yêu cầu được gửi tới máy chủ.
  • 400 BAD REQUEST: được sử dụng khi xác thực input phía client không thành công.
  • 401 UNAUTHORIZED / 403 FORBIDDEN: được sử dụng nếu người dùng hệ thống không được phép thực hiện một hành động nào đó.
  • 404 NOT FOUND: tìm một tài nguyên không có sẵn trong hệ thống, hoặc có thể sai đường dẫn URL.
  • 500 INTERNAL SERVER ERROR: thường là server bị lỗi.
  • 502 BAD GATEWAY: được sử dụng nếu máy chủ nhận được phản hồi không hợp lệ từ máy chủ ngược tuyến.

• Đánh dấu version: version của API là rất quan trọng, có nhiều cách sử dụng version như làm ngày tháng, làm tham số truy vấn, thông thường nhất là để làm tiền tố, ví dụ:

/v1/products
/v2/products

• Sử dụng phân trang: việc sử dụng phân trang là bắt buộc khi tài nguyên trả về lớn. Nên sử dụng Limit và Offset, ví dụ: /products?limit=25&offset=50. Nhưng khi số bản ghi trả về quá lớn, tức là khi offset quá to, thì việc sử dụng phân trang cũng không đem lại hiệu quả thực sự. Với trường hợp này, hãy xem bài viết tối ưu tại đây.

• Hỗ trợ các loại định dạng response: Hầu hết các ứng dụng hiện đại sẽ trả về phản hồi JSON trừ khi bạn có ứng dụng cũ vẫn cần nhận phản hồi XML.

• Sử dụng thông báo lỗi thích hợp: nên trả về đủ nghĩa nhất có thể, bao gồm kiểu lỗi, mã lỗi, messages,…

• SSL: Luôn sử dụng SSL. Đây là một trong những biện pháp bảo mật cơ bản khi thiết kế API. Cố gắng hiển thị endpoint của bạn thông qua SSL.

• Một số ví dụ về URLs and Actions — Relations:

GET /tickets/12/messages — Retrieves a list of messages for ticket #12
GET /tickets/12/messages/5 — Retrieves message #5 for ticket #12
POST /tickets/12/messages — Creates a new message in ticket #12
PUT /tickets/12/messages/5 — Updates message #5 for ticket #12
PATCH /tickets/12/messages/5 — Partially updates message #5 for ticket #12
DELETE /tickets/12/messages/5 — Deletes message #5 for ticket #12

Kết luận

Trên đây là một số kiến thức cơ bản về thiết kế RESTful API, giúp bạn thiết kế chúng một cách tốt hơn, tránh những nhầm lẫn không đáng có.

Tham khảo

RESTful API Desgign
Tìm hiểu Http request methods
Http methods docs