REST API - NHỮNG NGUYÊN TẮC VÀNG KHI THIẾT KẾ

Xin chào mọi người, tôi là John và đây là bài đầu tiên trong năm 2024 nên trước khi vào bài, tôi xin chúc mọi người 1 năm mới đầy thành công và đạt được nhiều thành tích tuyệt vời trong vũ trụ CODE nhé.

Bài hôm nay chúng ta sẽ nói về 1 anh bạn vô cùng quan trọng nếu bạn là 1 coder thì không thể không gặp anh bạn này, đây là cầu nối giao lưu giữa Front-End và Back-End trong 1 hệ thống, được ví như là một người phục vụ trong nhà hàng và anh bạn đó chính là REST API, nhân vật chính của bài viết ngày hôm nay.

Thế tại sao lại nói API được ví như 1 người phục vụ, để tôi vẽ 1 khung cảnh cho mọi người dễ hình dung nhé. Hãy tưởng tượng trong 1 nhà hàng, nhà bếp sẽ là nơi chế biến nguyên liệu từ những vật liệu ban đầu - cái tủ lạnh sẽ là Database, người đầu bếp đang chế biến thức ăn - Điều này giống như Back-End trong 1 hệ thống build 1 kiến trúc từ ERD, Configuration, Middleware…, bên ngoài là các bàn ăn sang trọng được sắp xếp gọn gàng sạch sẽ để đón khách - Điều này giống như Front-End thiết kế 1 giao diện bắt mắt, thân thiện với người dùng. Khi khách order 1 món ăn đến nhà bếp thì người phục vụ đem thông tin order đến cho các bếp làm món - Lúc này người phục vụ là cầu nối giữa khách và nhà bếp, điều này giống như khi User tương tác ở Front-End gửi request đến Back-End cũng cần có 1 phục vụ và REST API chính là người phục vụ đó.

Sơ qua thế mọi người cũng đã hiểu anh bạn API này có vai trò gì và vô cùng quan trọng trong hệ thống rồi đúng không nào. Cũng vì quá quan trọng nên các tiền bối đi trước đã đặt ra 9 Golden Rule khi thiết kế REST API để cho API được rõ ràng và dễ mở rộng, thôi chúng ta cùng nhau đi xem 9 Rule này mặt ngang mũi dọc ra sao nhá.

1. PROTOCOL RULE

• Trong thiết kế REST API, giao thức HTTPS được khuyên nên sử dụng thay vì HTTP vì 2 thằng này rất khác nhau, HTTPS vượt trội hơn HTTP nhiều. Nó có thể bảo mật thông tin trao đổi giữa client và server 1 cách an toàn, nó có tính riêng tư, tính chính xác và rất an toàn khi duyệt web. Đây chỉ là 1 đưa ra 1 vài lợi ích mặt nổi thôi nhưng đã rất đáng để sử dụng rồi ấy.

1. DOMAIN RULE

• Khi đặt tên domain, chúng ta nên đặt tên 1 cách nhất quán, có 2 sự lựa chọn cho domain api
• https://api.org.com/… → đặt api đi kèm với tên website (suggestion)
• https://org.com/api/…. → đặt tên website trước rồi / api

1. VERSION RULE

• Nên đặt version khi thiết kế API, ghi tắt là v-number, việc đặt version sẽ giúp chúng ta kiểm soát được thay đổi trong API, dễ dàng nâng cấp, triển khai và thử nghiệm các tính năng mới mà không làm ảnh hưởng đến ứng dụng hiện tại
• Example: https://api.org.com/v1/…. - https://api.org.com/v2/….

1. ENDPOINT RULE

• Trong thiết kế API, mỗi url sẽ đại diện cho 1 resource và 1 api cụ thể, tên của endpoint phải là DANH TỪ và nó tương ứng với tên của mỗi 1 table, nên đặt tên 1 cách rõ ràng, nhất quán để người khác chỉ cần đọc vào là hiểu ngay api này sẽ làm nhiệm vụ gì
• Example: https://api.org.com/v1/products…. - https://api.org.com/v2/users….

1. OPTIONS RULE

• Trong API chúng ta có những HTTP method để tương tác giữa Client và Server, đây chính là những chiếc cầu nối thứ thiệc và chúng ta sẽ có gồm khoảng 6 chiếc cầu được xem là sử dụng nhiều nhất này, nó sẽ là:
• HttpGet() - SELECT: Dùng để lấy resource, một hoặc nhiều từ server, cụ thể là từ database
• HttpPost() - CREATE: Tạo một resource mới lên server
• HttpPut() - UPDATE: Cập nhật resource lên server, client phải cung cấp các resource cần update, Put là để update nhiều field cùng 1 lúc, ví dụ như khi user cập nhật thông tin của mình
• HttpPatch() - UPDATE: Cập nhật resource lên server nhưng chỉ dành cho update 1 field, ví dụ như update status của user
• HttpDelete() - DELETE: Xóa resource khỏi server
• HttpHead() - GET: Lấy siêu dữ liệu từ Client như là token…

1. STATUS RULE

• Trong thiết kế API, Backend sẽ trả data về dưới dạng status, mỗi status sẽ biểu thị cho Frontend biết được kết quả như thế nào, dưới đây là những status phổ biến nhất
• 200 [Success]: Server return data successful
• 201 [Post/Put/Patch]: User create or update data successful
• 202 [Await/Async]: Cho biết một yêu cầu vào hàng đợi đã được chấp nhận, trong bất đồng bộ
• 204 [Delete]: User delete data successful
• 400 [Post/Put/Patch]: Có lỗi trong yêu cầu chỉnh sửa data từ client và server chưa thực hiện được request
• 401 [Unauthorized]: User login sai password, chưa đăng nhập hoặc sai access token
• 403 [Forbidden]: Ngược lại với 401, User đã login successful nhưng cố gắng access vào 1 website hoặc thực hiện 1 hành động không được phép, không có quyền truy cập
• 404 [Not Found]: Một yêu cầu của User mà server không tìm thấy và không thể return data, như get by id nhưng id đó không tồn tại trong database
• 406 [Not Acceptable]: Không có định dàng mà User require, ví dụ yêu cầu định dạng Json nhưng server chỉ có định dạng XML
• 410 [Not Exist]: Lỗi xuất hiện ở Client khi truy cập 1 resource đã từng tồn tại nhưng hiện tại thì không còn khả dụng, như là 1 website đã bị xóa
• 422 [Unprocessable Entity]: cho biết yêu cầu định dạng đúng nhưng nội dung hiển thị có 1 số error mà server không thể display lên được
• 500 [Internal Server Error]: Lỗi server, user không thể xác định request success or fail, nguyên nhân có thể do nhiều lượng truy cập cùng 1 lúc, xung đột Plugin, lỗi file….

1. ERROR HANDLE RULE

• Nên đưa ra những message thông báo lỗi 1 cách rõ ràng cho phía client biết, không nên chỉ return về status mà không có thêm thông tin gì, không nên ghi quá dài dòng ví dụ { error: “Invalid Token”, “Account or password wrong” }

1. RETURN RULE

• Khi thực hiện 1 method API nào, chúng ta nên return data tương ứng, tùy thuộc vào cách chúng ta thiết kế API
• Get / collection: Return về 1 list data
• Get / collection / resource: Return về 1 data duy nhất
• Post / collection: Return về data vừa được tạo
• Put / collection / resource: Return data hoàn chỉnh
• Patch / collection / resource: Return data hoàn chỉnh
• Delete / collection / resource: Return empty data

1. FILTERING RULE

• Và cuối cùng là Filtering, chúng ta có thể dùng nó để dễ dàng lấy data mình mong muốn hơn, có 4 cú pháp filter phổ biến nhất
• ?limit=10: Chỉ định số lượng bản ghi được trả về
• ?offset=10: Chỉ định vị trí bắt đầu của bản ghi được trả về
• ?page=2 &per_page=100: Chỉ định số page và số lượng trên mỗi page
• ?sortby=name&order=asc: Sắp xếp thuộc tính chỉ định theo thứ tự

Vậy là tôi đã giới thiệu xong cho mọi người 9 Golden Rule trong vũ trụ API rồi. Hãy tuân thủ theo nguyên tắc này thì API của mọi người mới có thể xanh-sạch-đẹp, hãy sửa thói quen design REST API từ ngay bây giờ nhé, sẽ giúp ích cho tương lai cho mọi người rất nhiều ấy. Hẹn gặp mọi người vào bài viết sau.