Thiết kế API – ba điều bắt buộc phải nắm rõ

32519

Bài viết được sự cho phép của tác giả Kiên Nguyễn

  3 bước tối ưu hiệu năng React App bằng các API mới của React
  API là gì? Tại sao API được sử dụng nhiều hiện nay?

1. Điều gì làm nên một API tốt?

Trước khi bắt đầu tìm hiểu sâu hơn về những nguyên tắc bắt buộc phải biết khi thiết kế API, ta cần định nghĩ rõ ràng với nhau. Như thế nào là một API tốt?, một API được đánh giá cao?.

Đây, câu này nghe khá là thấm (của Joshua Bloch):

APIs should be easy to use and hard to misuse

APIS nên dễ cho việc sử dụng đúng và khó cho sử dụng sai

Đấy, ai hỏi đừng có trả lời chi lòng vòng, cứ giải thích theo cách đơn giản nhất.

  • Một API thiết kế tốt thì dễ cho sử dụng đúng (đủ params, đúng URL, đúng token) thì trả về kết quả. Không rườm rà phức tạp.
  • Khó cho sử dụng sai (truyền sai, không đúng token, không có permission) thì không cho phép gọi xuống service để lấy kết quả

Đấy, tiêu chí chỉ vậy. Mở API document lên, bất cứ ông đẹp nào cũng hiểu API cung cấp những gì (what), bằng cách nào để thực hiện điều đó (how). Đấy là thiết kế API tốt

Trước khi bắt đầu hì hà hì hục implement cho từng API thì nên chú ý tới thiết kế API trước. Khâu thiết kế là vô cùng quan trọng.

It is such an important part when it comes to building an API that clients will love integrating with.


Đọc ở cuốn sách Production Ready GraphQL, tác giả viết hẳn phần design Schema đầu tiên. Đủ hiểu khi làm việc với API, thiết kế quan trọng như thế nào.

2. Tính ổn định (Stability) và nhất quán (Consistency)

Thường xuyên làm việc với API của Facebook mới thấm cảnh API thay đổi xoành xoạch. Rõ ràng tính ổn định đối với những API như vậy không cao. Tuy nhiên:

  • Facebook có hơn 1 tỷ người dùng, API thay đổi xoành xoạch cũng dễ hiểu. Nhiều feature cần implement.
  • Thay đổi là cần thiết để đáp ứng cho các nhu cầu mới, linh hoạt hơn.

Đó là chuyện của nhóm Dev cho công ty có hơn 2,6 tỷ người dùng. Còn thiết kế API mà anh em ta làm cho những project hoặc product cỡ trung bình, tính ổn định (Stability) nên được đem lên hàng đầu.

Anh em viết API nhiều cũng biết, cái implement đầu tiên khi release cho khách hàng là version 1. Sau này, khi bổ sung nhiều tính năng còn có thêm nhiều version khác nữa, …

Ngay từ ban đầu, nên clearly rõ ràng những thông tin version, đảm bảo tính nhất quán (Consistency) về sau (cứ lên version mới thì call với parameter function đó)

// Version kiểu params
http://appgido.com/api/information?version=1

// Hoặc kiểu này đều được
http://appgido.com/api/information/v1

Về tính nhất quán khi thiết kế và làm việc với API thì còn nhiều điều có thể áp dụng hoặc tránh đi.

  • Nếu đã sử dụng GraphQL để call API thì sử dụng đồng bộ, không nửa này nửa kia.
  • Sử dụng 2 field name mang cùng ý nghĩa, chỉ khác tên. Ví dụ: companyCode và companyVendorCode
  • Nếu đã sử dụng verbs (động từ) thì dùng cả. Đừng có chỗ thì dùng HTTP METHOD, chỗ lại createStudent, deleteStudent.
  • Một số API hỗ trợ PATCH, một số thì không.
  • Document khi field đó là require cho việc gọi API, nhưng không giải thích tại sao, truyền dư params, …

3. Tính linh hoạt (Flexibility)

Đơn giản nhất để hình dung về tính linh hoạt là Accept and Content-Type Headers. Hiện tại, thiết kế API cho version 1.0 có thể cho phép Accept kiểu JSON, nhưng sau này sẽ thêm XML.

Trường hợp những developer khác muốn sử dụng Content Type khác, API có thể chấp nhận được không?

Thiết kế API – ba điều bắt buộc phải nắm rõ
Có linh hoạt cho sử dụng các types khác nhau hay không?. Một câu hỏi lớn khi thiết kế API

Khả năng linh hoạt khi thiết kế API còn phụ thuộc vào tính ràng buộc khi gửi request. Field nào thì bắt buộc, field nào không. Trường hợp field đó flexible thì tốt cho API Service hay không?

4. Tính bảo mật (Security)

Trước thì ít có ông nào thiết kế API mà lại lo tới cả bảo mật. Chủ yếu dùng JWT hoặc BearToken là xong. Tuy là tiện, nhưng anh em nhớ check lại dùm việc xác thực, cấp token có chính xác không?. Có thuận lợi không?.

Những API quan trọng thì bảo mật ở đâu?, có dễ bị attack hay không?.

Túm cái váy lại, một số thứ cần nhớ trong đầu để thiết kế API tốt là:

  • APIs generally allow you to do basic create, read, update, and delete operations on data – API về cơ bản cho phép CREATE, READ, UPDATE và DELETE data
  • Trước khi bắt đầu nhớ take care về Authozation với Authentication (Xác thực và phân quyền cho từng user). Đừng có ông nào không cần permission mà vẫn gọi API DELETE /user/id
  • Về phần security, nhớ nghía qua Cross-Site Request Forgery (CSRF), cẩn thận kẻo bị tấn công kiểu này

5. Tham khảo thêm về thiết kế API

Chốt, hết bài rồi!. Anh em thấy hay nhớ like và share bài viết trên Facebook nha. Happy coding!

Bài viết gốc được đăng tải tại kieblog.vn

Có thể bạn quan tâm:

Xem thêm các việc làm Developer hấp dẫn tại TopDev

RELATED ARTICLESMORE FROM AUTHOR