Thiết kế RESTful API

Bài đăng này đã không được cập nhật trong 2 năm

Lời mở đầu

Trong thế giới kết nối như bây giờ, một sản phẩm không thể đứng độc lập, và sản phẩm nào không có APIs, giống như máy tính không được kết nối Internet vậy. Việc xây dựng một API là một trong những điều quan trọng nhất bạn có thể làm để nâng cao giá trị dịch vụ của bạn. Bởi việc có một API thì dịch vụ hay ứng dụng của bạn mới có khả năng trở thành một nền tảng mà từ đó các dịch vụ khác sẽ phát triển theo. Hãy cùng xem những công ty hiện tại như: Facebook, Twitter, Google, GitHub, Amazon, Netflix…, sẽ không có một công ty nào có thể lớn mạnh như ngày nay nếu như họ không cung cấp mở những dữ liệu của họ thông qua API.

Thiết kế RESTful API như thế nào?

Tại sao lại là RESTful?, có khá nhiều bài post về chủ đề này, nhưng có lẽ chúng ta đều đồng ý rằng APIs trong thời đại hiện nay đều sử dụng chuẩn RESTful.

Những hành động CRUD sử dụng những phương thức HTTP

GET (SELECT): Trả về một Resource hoặc một danh sách Resource.
POST (CREATE): Tạo mới một Resource.
PUT (UPDATE): Cập nhật thông tin cho Resource.
PATCH (UPDATE): Cập nhật một thành phần, thuộc tính của Resouce.
DELETE (DELETE): Xoá một Resource.
HEAD – Trả về thông tin chung của một hoặc danh sách Resource.
OPTIONS – Trả về thông tin mà người dùng được phép với Resource.

Dữ liệu trả về JSON only?

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.

// snake_case
{
    user_id: 1,
    full_name: "Le Quang Canh"
}
 
// camelCase
{
    userId: 1,
    fullName: "Le Quang Canh"
}

Số ít hay số nhiều

Danh từ số nhiều: Mặc dù là sẽ có những ngữ cảnh mô tả một trường hợp trong những Resource nhưng trong thực tế để giữ cho định dạng URL nhất quán thì sẽ nên luôn luôn sử dụng số nhiều. Không phải đối phó với những danh từ (person/people, goose/geese) sẽ làm những người sử dụng API thấy dễ chịu hơn và cũng sẽ cho bên cung cấp API dễ thực thi nó (/tickets và tickets/12 thường được viết trong một controller chung) GET /tickets – Trả về danh sách những ticket GET /tickets/12 – Trả về một ticket được định danh POST /tickets – Tạo mới một ticket PUT /tickets/12 – Cập nhật thông tin cho ticket #12 PATCH /tickets/12 – Cập nhật một thuộc tính cho ticket #12 DELETE /tickets/12 – Xóa ticket #12 Nếu tồn tại một quan hệ duy nhất với Resource khác, RESTful cung cấp những hướng dẫn có ích. Ví dụ: GET /tickets/12/messages – Trả về danh sách message của ticket #12 GET /tickets/12/messages/5 – Trả về message #5 của ticket #12 POST /tickets/12/messages – Tạo mới một message trong ticket #12 PUT /tickets/12/messages/5 – Cập nhật message #5 của ticket #12 PATCH /tickets/12/messages/5 – Cập nhật một số thuộc tính của message #5 cho ticket #12 DELETE /tickets/12/messages/5 – Xoá message #5 for ticket #12

Không sử dụng động từ: GET /getAllCars POST /createNewCar DELETE /deleteAllRedCars

Authentication

RESTfull API không sử dụng session à cookie, bởi vậy nên sử dụng một mã bí mật access_toket với mỗi request. Luôn sử dụng SSL https://example.com/users?access_token=xxxxxxxx

Dữ liệu trả về

Rất nhiều API được bao bọc như:

{
    "data" : {
        "id": "1",
        "name": "Canh"
    }
}

Pagination

Hãy luôn sử dụng pagination. Trả về đầy đủ danh sách khách hàng qua APIhttp://api.shop.me/customers là việc tốn kém tài nguyên, đồ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, page_size… để client có thể chỉ định http://api.shop.me/orders?page=4&page_size=10. Luôn sử dụng page_size 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

200 OK – Trả về thành công cho những phương thức GET, PUT, PATCH hoặc DELETE.
201 Created – Trả về khi một Resouce vừa được tạo thành công.
204 No Content – Trả về khi Resource xoá thành công.
304 Not Modified – Client có thể sử dụng dữ liệu cache.
400 Bad Request – Request không hợp lệ
401 Unauthorized – Request cần có sự authentication.
403 Forbidden – Server hiểu request nhưng bị từ chối không cho phép.
404 Not Found – Không tìm thấy rource từ URI
405 Method Not Allowed – Phương thức không cho phép với user hiện tại.
410 Gone – Resource không còn tồn tại, Version cũ đã không còn hỗ trợ.
415 Unsupported Media Type
422 Unprocessable Entity – Dữ liệu không được kiểm chứng
429 Too Many Requests – Request bị từ chối do bị giới hạn

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.

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.