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

Để thiết kế một API tốt thật sự là một điều rất khó. Tài liệu thiết kế API rất quan trọng nhưng cũng thật khó để tìm ra một lập trình viên thích viết tài liệu mô tả cho nó.
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ế API có rất nhiều quan điểm, dưới đây là một vài mô tả hữu dụng cho việc có thể thiết kế tốt.

1. 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.

2. Sử dụng danh từ số nhiều, không dùng động từ

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

3. 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.

4. Lọc kết quả, sắp xếp, tìm kiếm, phân trang

Lọc kết quả: Sử dụng một biến duy nhất cho mỗi trường được lọc.
    GET /tickets?state=open – Lấy duy nhất trạng thái đang open từ danh sách ticket
    GET /cars?seats<=2 Trả về một danh sách những oto với số ghế tối đa là 2

Sắp xếp: Sử dụng tham biến "sort" để mô tả luật sắp xếp.
    GET /tickets?sort=-priority – Trả về một danh sách những ticket được sắp xếp theo priority giảm dần.
    GET /tickets?sort=-priority,created_at – Trả về một danh sách những ticket được sắp xếp theo priority giảm dần. Với một ticket cùng priority, những ticket cũ sẽ được sắp xếp trước.

Tìm kiếm: Đôi khi những điều kiện lọc cơ bản không đủ và bạn cần đến full text search. Sử dụng tham biến “q”, một tham biến được dùng trong ElasticSearch hoặc Lucene.
    GET /tickets?q=keyword&state=open&sort=-priority,created_at

Giới hạn dữ liệu được trả về: Sử dụng tham biến "fields"
    GET /tickets?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at

Phân trang: Sử dụng page và per_page
    GET /ticket?page=1&per_page=100
Hoặc có thể sử dụng mặc định limit và offset:
    GET /ticket?offset=10&limit=100

5. Snake_case hay camelCase

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.

6. Pretty print và gzip cần được hỗ trợ

Một API mà những khoảng trắng, ký tự space đã được nén lại thì thật không vui khi mà phải quan sát từ Browser. Và khi sử dụng Gzip có thể giúp tiết kiệm đến 60% băng thông.

7. 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

8. Caching

Có 2 phương pháp nên được áp dụng là Etag và Last-Moified.

9. Dữ liệu trả về

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

Dữ liệu trả về nhiều khi bao bọc là không thật sự cần thiết theo CORS và Link header from RFC 5988.
Một vài REST client không cho phép truy cập tới HTTP header và cũng như JSONP không có quyền truy cập vậy, do vậy có thể bao bọc dữ liệu trả về trong những trường hợp cần thiết.

10. Lỗi

Có những lúc bạn muốn tuỳ biến định dạng lỗi mặc định được trả về, ví dụ như sử dụng những trạng thái, mã HTTP khác để chỉ ra những lỗi khác nữa, một lời khuyên bạn nên luôn sử dụng mã 200 và những mã lỗi thực sẽ là một thành phần của cấu trúc JSON được trả về giống như là sau:

11. Những mã HTTP thường được sử dụng

• 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

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.

Tài liệu liên quan

[1] https://codeplanet.io/principles-good-restful-api-design/
[2] http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api