Một vài kinh nghiệm viết API

Để xây dựng API phong phú và chuyên nghiệp thì có rất nhiều điều chúng ta cần xem xét từ khi bắt đầu. Sau đây tôi xin chia sẻ một vài kinh nghiệm trong quá trình phát triển dự án thực tế.

Sử dụng phiên bản

Ngay cả khi bạn bắt đầu phát triển sản phẩm và bạn không chắc chắn rằng bạn sẽ có cơ hội để tạo phiên bản API tiếp theo, vẫn hãy xây dựng phiên bản cho API của bạn. Khi sản phẩm của bạn thành công thì bạn sẽ luôn muốn cải thiện API của mình, và khi đó việc xây dựng nên phiên bản tiếp theo sẽ dễ dàng hơn rất nhiều.

Nguyên lý ở đây rất đơn giản: việc thay đổi một API đã được công bố thực sự rất tồi. Khách hàng của bạn đang phát triển sản phẩm quan trọng dựa vào giao diện API của bạn. Khi bạn thay đổi giao diện API thì họ cũng phải thay đổi theo. Điều này khả năng lớn sẽ phát sinh lỗi. Với Rails, bạn có thể dùng namespace để xác định các phiên bản API khác nhau như sau:

namespace :api do
  namespace :v1 do
    resources :projects
  end
end

Đoạn code như trên sẽ dẫn tới URL như sau: /api/v1/projects

Sử dụng mã trạng thái HTTP chính xác

HTTP cung cấp cho bạn một cơ chế tuyệt vời để thông báo cho những người dùng API của bạn kết quả của request: HTTP status codes

Sử dụng các status code đó đúng sẽ cung cấp cho người dùng những thông tin hữu dụng. Bảng dưới đây là một số HTTP status codes điển hình của REST-API:

Rails controller giúp cho việc trả về mã trạng thái thuận tiện như sau:

render json: @object, status: :created

Sử dụng JSON

Hiện tại phía client thì định dạng dữ liệu phổ biến và dễ phân tích là JSON. Vì vậy để đảm bảo API của bạn được phổ biến và thu hút được nhiều người dùng thì bạn nên trả về kết quả với định dạng JSON.

Trả về đúng hành động HTTP

Bên cạnh những HTTP status codes vô cùng hữu ích, bạn cũng nên sử dụng đúng HTTP verbs. Phổ biến nhất mà bạn cần trong bất kỳ REST-API nào là:

Trả về thông báo lỗi đầy đủ

Việc xử lý lỗi trong API cần thực sự cẩn thận. Tốt nhất chúng ta luôn luôn trả về thông báo lỗi với cùng một định dạng (format) giúp người dùng không phải viết nhiều cách thức phân tích kết quả trả về khác nhau.

Một ví dụ về thông báo lỗi tốt như sau:

{
  "status": 422,
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "Project",
      "field": "name",
      "message": "can't be blank"
    }
  ]
}

Luôn luôn phân trang cho kết quả trả về

Với những request trả về số lượng kết quả thấp thì chúng ta chưa thấy được tác dụng của việc phân trang. Tuy nhiên, khi một request trả về tới hàng chục nghìn/trăm nghìn kêt quả thì gánh nặng rất lớn sẽ đè lên client. Cách tốt nhất là hãy luôn thực hiện phân trang kết quả trả về của bạn. Số lượng kết quả trên mỗi trang thì có thể phụ thuộc vào từng tình huống cụ thể.

Xác thực người dùng

Nếu như bạn đang xây dựng API không công khai thì rất cần thiết để xác thực các quyền người dùng.

Bạn có thể xác thực bằng Basic Authentication, Devise. Tất cả đều có thể dễ dàng thực hiện trong Rails.

Giới hạn truy cập

Khi người dùng bắt đầu sử dụng API của bạn, bạn có thể không phải lo lắng về hiệu suất hoặc giới hạn tài nguyên của bạn.Tuy nhiên, nếu ứng dụng của bạn thành công và có đến hàng nghìn người dùng bắt đầu tích hợp API vào cơ sở hạ tầng và quy trình làm việc của họ, mọi thứ có thể sẽ sai. Vì vậy, để tránh lạm dụng, thì bạn nên xem xét việc thêm rate-limiting vào API của bạn.

Ví dụ, bạn có thể muốn giới hạn việc sử dụng API của mỗi người dùng được nhiều nhất là 1000 lần gọi API trong khoảng thời gian là 10 phút. Nếu có quá nhiều request được nhận từ một người dùng trong một khoảng thời gian nhất định, một response với status code là 429 (Có nghĩa là "Có quá nhiều request") nên được trả về.

Khi rate limiting được enabled, mặc định mọi response sẽ được gửi đi kèm với HTTP headers có chứa những thông tin rate limiting hiện tại:

X-Rate-Limit-Limit: số request tối đa được cho phép trong một khoảng thời gian X-Rate-Limit-Remaining: số request còn lại trong khoảng thời gian X-Rate-Limit-Reset: số giây chờ đợi để có thể bắt đầu gọi API từ đầu

Trên đây là một số điều mình tham khảo và rút ra được từ dự án phát triển API hiện tại. Còn nhiều lưu ý khác, mình sẽ tiếp tục kiểm nghiệm và cập nhật thêm vào bài viết này.

Cám ơn bạn đã theo dõi bài viết!!!

Tài liệu tham khảo: https://phraseapp.com/blog/posts/best-practice-10-design-tips-for-apis/