RESTfull API là thuật ngữ thường gặp trong lập trình, và để hiểu được thuật ngữ này thì rất quan trọng, Trong bài viết này mình sẽ giới thiệu sơ lược về nó là cái gì (What ?), tại sao phải dùng nó (Why ?) và dùng nó như thế nào (How ?)

• What ? : REST viết tắt của - Representational State Transfer- Giải thích đơn giản, REST là một loạt hướng dẫn và dạng cấu trúc dùng cho việc chuyển đổi dữ liệu. ) Là 1 kiểu kiến trúc lập trình, định nghĩa các quy tắc để thiết kế web service chú trọng vào tài nguyên Mọi thứ trong REST đều được coi là tài nguyên và được định danh thông qua URI, và có thể được biểu diễn thông qua dạng văn bản, XML, JSON …. RESTful là những ứng dụng mà có sử dụng kiến trúc REST
• Why ?
• Thiết kế web trước đây sử dụng SOAP (Simple Object Access Protocol) và WSDL (Web Service Definition Language), tuy nhiên bây giờ REST tối ưu hơn so với 2 phương pháp này.
• Rõ ràng về URL (REST URL đại diện cho resource xác định chứ không phải hành động)
• Trả về nhiều định dạng khác nhau như: html, xml, json …
• Hiệu suất tốt, tin cậy, dễ phát triển.
• Việc tuân theo một tiêu chuẩn khi thiết kế ứng dụng cũng sẽ giúp các lập trình viên dễ dàng cộng tác được với nhau hơn khi dự án đòi hỏi một số lượng lớn các lập trình viên tham gia.

  Ràng buộc trong REST

• Client - Server: Hoạt động theo mô hình Client - Server, Server là tập hợp các service nhỏ lắng nghe các request từ Client. Với từng request khác nhau thì có thể một hoặc nhiều service xử lý.
• Stateless - phi trạng thái: Hiểu đơn giản là Server và Client không lưu trạng thái của nhau. Với mỗi request được gửi đi thì phải được đóng gói đầy đủ thông tin để cho thằng server có thể nhận và hiểu được.
• Khả năng caching: Các response có thể lấy từ cache. Bằng cách cache các response cần thiết sẽ giảm tải việc xử lý request của thằng server -> client nhận thông tin phản hồi nhanh hơn.
• Chuẩn hóa Interface: Nhằm đơn giản hóa và tách biệt kiến trúc, cho phép từng phần phát triển độc lập,, người phát triển đã tạo ra API cơ bản để thiết kế bất kỳ dịch vụ REST nào (dù là web hay mobile thì đều có thể kết nối vào được). Tuy nhiên khi chuẩn hóa thì ta không thể tối ưu từng kết nối được.
• Phân lớp hệ thống: giảm mức độ phức tạp của hệ thống, giúp các thành phần tách biệt nhau từ đó dễ dàng mở rộng. Với mỗi một lớp chỉ trao đổi trực tiếp với lớp ngay dưới và trên nó.

Hệ thống REST trước hết phải tuân thủ các ràng buộc ở trên. Đi vào chi tiết, hệ thống REST tập trung vào việc xử lý các tài nguyên. Resource là bất cứ cái gì mà bạn có thể gọi tên được ( một video, ảnh, trang web, báo cáo thời tiết .v.v). Các tài nguyên này giúp ta định nghĩa được các services trong hệ thống, kiểu thông tin mà nó trả về, và hành vi xử lý thông tin của nó. Thông thường nhắc đến REST là nhắc đến HTTP vì hệ thống REST thường sử dụng giao thức HTTP. Hệ thống REST xoay quanh viêc đơn giản hóa việc lấy các representation của một tài nguyên hệ thống. Những hành động CRUD sử dụng những phương thức HTTP

Ví dụ:

Dữ liệu trả về

Hầu hết những người viết RESTful API giờ đây đều chọn JSON là format chính thức nhưng rất nhiều người vẫn phân vân với câu hỏi “chỉ JSON hay hỗ trợ thêm XML?”. Tất nhiên, có hàng tá lý do để chúng ta hỗ trợ thêm những format khác, đặc biệt là XML. Tuy nhiên, hỗ trợ nhiều định dạng chỉ làm cho việc kiểm thử API thêm phức tạp.

Snake_case hay camelCase

Việc sử dụng snake case hay camel case chủ yếu do sở thích của lập trình viên thôi, không có lý do gì để phân định được. Nhiều nghiên cứu chỉ ra rằng snake_case dễ đọc hơn camelCase khoảng 20% và rất nhiều những API phổ biến đều sử dụng snake_case. Và theo cá nhân mình thì nên chọn kiểu Snake_case

1
2
3
4
5
6
7
8
9
10
11
// snake_case
{
    user_id: 1,
    full_name: "Nguyen Van Tan"
}
 
// camelCase
{
    userId: 1,
    fullName: "Nguyen Van Tan"
}

Authenticate

RESTfull API không sử dụng session hay cookie, vì vậy nên sử dụng 1 mã bí mật là access_token kèm theo lúc gửi request.

Định dạng dữ liệu trả về

Cái này thì tùy theo mỗi cá nhân mỗi người trả về như nào, Bạn có thể tham khảo cách của mình. Mình cũng tham khảo của nhiều người rồi mới được như này:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Success:
{
  "status": true,
  "data": {
    // data response here
  },
  "error": {
    "code": 0,
    "message": ""
  }
}
Error: 
{
  "status": false,
  "data": {},
  "error": {
    "code": 404|500|401..,
    "message": "message you response"
  }
}

Hoặc bạn có thể tham khảo ở một số trang khác trên Internet.

Pagination

Hãy luôn sử dụng pagination. Trả về đầy đủ danh sách khách hàng qua API là việc tốn kém tài nguyên, tăng thời gian truy vấn DB, đồng thời không hữu dụng. Bởi client cũng sẽ giới hạn lại danh sách này nhằm đáp ứng một giao diện dễ nhìn cho người dùng.Hãy để thêm những param cố định trong mỗi API trả về một danh sách dữ liệu như /customers,/orders: page, limit… để client có thể chỉ định http://api.shop.me/orders?page=4&limit=10. Luôn sử dụng limit mặc định để giới hạn dữ liệu trả về ngay cả khi người dùng không chỉ định rõ trong lời gọi API.Tất nhiên, pagination thì có hàng chục cách, trên đây chỉ là một ví dụ.

Status code

Version

Hãy luôn sử dụng version trong API của bạn. Version sẽ giúp bạn lặp lại nhanh hơn và ngăn ngừa được những request không hợp lệ. Nó cũng sẽ giúp bạn suôn sẻ dễ dàng khi chuyên đổi những version API hay như là bạn có thể tiếp tục cung cấp các những version cũ trong một khoảng thời gian. https://example.org/api/v1/https://api.example.com/v1/ Nếu ứng dụng của bạn lớn, sự lựa chọn tốt nhất nên đặt API ở subdomain (api). Nó có thể giúp làm giảm được sự tải trang.

Document

Bạn nên tập cách viết document cho API của bạn, để những thành viên khác khi dùng thì họ còn biết API của bạn mô tả gì, trả về những gì hoặc có những mã lỗi nào. Và cũng để sau này bạn đọc lại code của mình còn hiểu chứ thật sự sau một vài năm thì nhìn vào đống code của mình chả hiểu nó làm cái quái gì. Có một số tool hỗ trợ cho bạn viết doc như https://swagger.io/ https://www.apimatic.io/

Tổng kết

Một API như là một User Interface cho những người phát triển. Hãy cố gắng để đảm bảo nó không chỉ là chức năng mà còn làm người sử dụng thấy dễ dàng khi sử dụng.