Nguồn
Good APIs Vs Bad APIs: 7 Tips for API Design
Đặt tên rõ ràng
Khi xây dựng API, chọn tên rõ ràng và hợp logic. Thay vì dùng /cart/123 cho một app mua hàng, hãy sử dụng /carts/123. Danh từ số nhiều sẽ cho người sử dụng API biết rằng mình đang làm việc với một tập các tài nguyên. Hãy nhất quán, nó sẽ giúp người dùng dễ dàng hơn khi sử dụng API của bạn.
Đảm bảo độ tin cậy của các idempotent API
Idempotency nghĩa là làm cho việc gọi API nhiều lần cũng giống như gọi một lần. Ý tưởng này là chìa khóa cho các API tin cậy, giúp tránh lỗi khi API được gọi lại, có thể do lỗi mạng.
Thông thường, các request POST không phải idempotent vì gửi một request POST hai lần có thể tạo ra hai object giống nhau.
Ta có thể thêm logic để tránh tạo ra các object giống nhau, bằng cách sinh một ID mới cho các request khác nhau.
Các request GET thì thường idempotent. Các request GET giống nhau sẽ trả về thông tin như nhau.
Các request PUT sẽ update toàn bộ object nên cũng thường là idempotent. Tuy nhiên, các request PATCH thì lại update một số trường của object thôi. Ví dụ, nếu bạn gửi PATCH request hai lần để thêm một màu xanh vào một trường màu (một mảng), ta sẽ có hai màu xanh trong mảng đó. Vì vậy, PATCH request không phải idempotent.
Cuối cùng, các request DELETE sẽ idempotent. DELETE sẽ chỉ thực hiện một lần khi gọi nhiều lần. Nếu object đã bị xóa thì DELETE sẽ chỉ trả về lỗi gì đó thôi, còn thông tin của object đã bị xóa sẽ không còn.
Thêm phiên bản (versioning) vào API
API sẽ phát triển và cần update liên tục. Bạn sẽ cần phải update mà không làm gián đoạn hoạt động hiện tại của ứng dụng. Một URL kiểu v1/carts/123 sẽ giúp bạn update thành v2/carts/123 mà không ảnh hưởng đến những người đang sử dụng API trước đó.
Việc thêm phiên bản sẽ giúp hỗ trợ cả những người dùng cũ và mới, giúp người sử dụng nâng cấp bất kỳ lúc nào mà họ muốn và giúp cho việc tài liệu hóa API dễ dàng hơn.
Thêm phân trang
Phân trang giúp kiểm soát số lượng tài nguyên trả về khi gọi API. Những cách phân trang phổ biến bao gồm: Page + Offset và Cursor-based.
Phân trang kiểu Page + Offset sử dụng số trang và số lượng tài nguyên trên mỗi trang. Ví dụ, trang 2 sẽ bao gồm các tài nguyên đánh số từ 11 đến 20 khi mỗi trang có 10 tài nguyên. Rất đơn giản, nhưng có thể chậm đi với tập du liệu lớn, vì database sẽ phải đếm tất cả các dòng từ đầu cho đến trang cần trả về.
Phân trang kiểu Cursor-based sử dụng một con trỏ để xác định vị trí của tài nguyên trong tập dữ liệu. Nó theo dấu tài nguyên một cách chính xác, dù với tập dữ liệu thay đổi liên tục.
Phân trang giúp tránh việc trả về quá nhiều dữ liệu mà người dùng không cần, giúp giảm tải cho server và cải thiện trải nghiệm người dùng.
Sử dụng truy vấn rõ ràng để sắp xếp và lọc dữ liệu
Ví dụ, nếu bạn muốn sắp xếp các user theo ngày đăng ký tài khoản, dùng truy vấn kiểu /users?sort_by=registered. Nếu muốn lọc ra các product có màu xanh chẳng hạn, dùng /products?filter=color:blue.
Lợi thế ở đây là gì?
- Query string kiểu này giúp ta truy vấn một cách tự nhiên, dễ đọc và dễ hiểu.
- Bạn có thể thêm điều kiện lọc bất kỳ lúc nào bạn muốn mà không làm thay đổi cấu trúc của API.
- Kết quả lọc và sắp xếp có thể được cache ở đâu đó giúp giảm tải cho server.
Hãy quan tâm đến bảo mật
Với các credential nhạy cảm như API key, bạn nên cho vào header thay vì dùng trực tiếp trên URL. URL sẽ được log trên server và người ta có thể dễ dàng thấy được nó. Các header như Authorization giúp tránh tình trạng đó.
Tuy nhiên, header vẫn có thể làm rò rỉ thông tin, vì vậy bạn nên mã hóa TLS cho API của mình.
Kiểm soát truy cập (Access Control) chặt chẽ cho các API, xác thực tất cả các key hay token nhận được trước khi xử lý API.
Bảo mật là một chủ đề rộng lớn, ta chỉ chạm vào phần nhỏ ở đây thôi. Hãy tìm hiểu thêm về bảo mật API để đảm bảo API của bạn an toàn nhé.
Đơn giản hóa việc truy vấn đa tài nguyên
Truy vấn đa tài nguyên cần rõ ràng và đơn giản. Ví dụ, ta dùng carts/123/items/321 để lấy thông tin item 321 trong cart 123, không nên dùng items?cart_id=123&item_id=321. Điều này giúp việc tích hợp trở nên dễ dàng hơn.
Bonus: Sử dụng rate limiting
Rate limiting giúp giảm tải cho server, tránh bị quá tải hoặc tấn công. Ta có thể dùng một số tiêu chí như địa chỉ IP, tài khoản người dùng, hay các API để giới hạn số lượng request mà một người dùng có thể gửi trong một khoảng thời gian nhất định.
Ví dụ, người dùng miễn phí có thể gọi 1000 request mỗi ngày, và mỗi địa chỉ IP có thể gọi 20 lần mỗi phút.
Website không chứa bất kỳ quảng cáo nào, mọi đóng góp để duy trì phát triển cho website (donation) xin vui lòng gửi về STK 90.2142.8888 - Ngân hàng Vietcombank Thăng Long - TRAN VAN BINH
=============================
Nếu bạn không muốn bị AI thay thế và tiết kiệm 3-5 NĂM trên con đường trở thành DBA chuyên nghiệp hay làm chủ Database thì hãy đăng ký ngay KHOÁ HỌC ORACLE DATABASE A-Z ENTERPRISE, được Coaching trực tiếp từ tôi với toàn bộ bí kíp thực chiến, thủ tục, quy trình của gần 20 năm kinh nghiệm (mà bạn sẽ KHÔNG THỂ tìm kiếm trên Internet/Google) từ đó giúp bạn dễ dàng quản trị mọi hệ thống Core tại Việt Nam và trên thế giới, đỗ OCP.
- CÁCH ĐĂNG KÝ: Gõ (.) hoặc để lại số điện thoại hoặc inbox https://m.me/tranvanbinh.vn hoặc Hotline/Zalo 090.29.12.888
- Chi tiết tham khảo:
https://bit.ly/oaz_w
=============================
2 khóa học online qua video giúp bạn nhanh chóng có những kiến thức nền tảng về Linux, Oracle, học mọi nơi, chỉ cần có Internet/4G:
- Oracle cơ bản: https://bit.ly/admin_1200
- Linux: https://bit.ly/linux_1200
=============================
KẾT NỐI VỚI CHUYÊN GIA TRẦN VĂN BÌNH:
📧 Mail: binhoracle@gmail.com
☎️ Mobile/Zalo: 0902912888
👨 Facebook: https://www.facebook.com/BinhOracleMaster
👨 Inbox Messenger: https://m.me/101036604657441 (profile)
👨 Fanpage: https://www.facebook.com/tranvanbinh.vn
👨 Inbox Fanpage: https://m.me/tranvanbinh.vn
👨👩 Group FB: https://www.facebook.com/groups/DBAVietNam
👨 Website: https://www.tranvanbinh.vn
👨 Blogger: https://tranvanbinhmaster.blogspot.com
🎬 Youtube: https://www.youtube.com/@binhguru
👨 Tiktok: https://www.tiktok.com/@binhguru
👨 Linkin: https://www.linkedin.com/in/binhoracle
👨 Twitter: https://twitter.com/binhguru
👨 Podcast: https://www.podbean.com/pu/pbblog-eskre-5f82d6
👨 Địa chỉ: Tòa nhà Sun Square - 21 Lê Đức Thọ - Phường Mỹ Đình 1 - Quận Nam Từ Liêm - TP.Hà Nội
=============================
cơ sở dữ liệu, cơ sở dữ liệu quốc gia, database, AI, trí tuệ nhân tạo, artificial intelligence, machine learning, deep learning, LLM, ChatGPT, DeepSeek, Grok, oracle tutorial, học oracle database, Tự học Oracle, Tài liệu Oracle 12c tiếng Việt, Hướng dẫn sử dụng Oracle Database, Oracle SQL cơ bản, Oracle SQL là gì, Khóa học Oracle Hà Nội, Học chứng chỉ Oracle ở đầu, Khóa học Oracle online,sql tutorial, khóa học pl/sql tutorial, học dba, học dba ở việt nam, khóa học dba, khóa học dba sql, tài liệu học dba oracle, Khóa học Oracle online, học oracle sql, học oracle ở đâu tphcm, học oracle bắt đầu từ đâu, học oracle ở hà nội, oracle database tutorial, oracle database 12c, oracle database là gì, oracle database 11g, oracle download, oracle database 19c/21c/23c/23ai, oracle dba tutorial, oracle tunning, sql tunning , oracle 12c, oracle multitenant, Container Databases (CDB), Pluggable Databases (PDB), oracle cloud, oracle security, oracle fga, audit_trail,oracle RAC, ASM, oracle dataguard, oracle goldengate, mview, oracle exadata, oracle oca, oracle ocp, oracle ocm , oracle weblogic, postgresql tutorial, mysql tutorial, mariadb tutorial, ms sql server tutorial, nosql, mongodb tutorial, oci, cloud, middleware tutorial, docker, k8s, micro service, hoc solaris tutorial, hoc linux tutorial, hoc aix tutorial, unix tutorial, securecrt, xshell, mobaxterm, putty