Code Dạo, Lập Trình

Thiết kế Rest API thế nào cho đúng?

Như các bạn đã biết, việc thiết kế REST API là một việc hết sức khó khăn. Nó không đơn giản như...

Written by AnonyHome
· 4 min read >
Restful API trong 5 phút - AnonyHome

Như các bạn đã biết, việc thiết kế REST API là một việc hết sức khó khăn. Nó không đơn giản như việc chỉ viết ra để cho client gọi là xong. Đôi khi chúng ta gặp những vấn đề là nên viết API như thế này hay viết như thế kia mặc dù cho tất cả các nghiệp vụ bạn đã xử lý xong. Vì vậy, chúng ta cần phải có các nguyên tắc để thiết kế REST API cho hệ thống để giải quyết các vấn đề đó. Trong bài viết này mình sẽ chia sẻ một số kinh nghiệm của bản thân trong trong việc thiết kế REST API này.

Xem thêm: Restful API trong 5 phút – AnonyHome

Đối với cá nhân mình, một hệ thống có chất lượng thiết kế API tối cần đáp ứng những yếu tố sau:

  1. Self-documenting (nhìn vào API ta có thể đoán ra được nó dùng để làm gì)
  2. Flexible (tính mở rộng cũng như tuỳ biến của API)
  3. Unified structure and attribute names(thống nhất về mặt cấu trúc cho resource cũng như cách đặt tên cho các attribute)
  4. Clear error message (khi hệ thống xảy ra lỗi thì message phải rõ ràng và chi tiết để phục vụ cho quá trình fix bug)

Để đáp ứng những những yếu tố trên thì chúng ta sẽ phải tuân thủ các nguyên tắc sau đây:

Sử dụng HTTP method để mô tả về chức năng của resource:

Chúng ta có 4 HTTP method cơ bản bao gồm POST, GET, PUT, DELETE. Với mỗi method sẽ ứng với một chức năng tương ứng của API là tạo, đọc, sửa và xoá.

Sử dụng danh từ số nhiều, không sử dụng động từ trong REST API.

  • GET /cars
  • POST /cars
  • PUT /cars/123
  • DELETE /cars/123

Một số resource URIs nên thiết kế như sau:

  • http://api.example.com/cars
  • http://api.example.com/cars/{id}
  • http://api.example.com/users
  • http://api.example.com/users/{id}
  • http://api.example.com/users/{id}/cars

Không nên sử dụng thế này:

Versioning

Versioning là một điều bắt buộc với tất cả resource, việc đánh version cho resource tuân thủ 2 nguyên tắc sau:

  • Bắt đầu bằng “v” và kết thúc bằng một số nguyên dương , tránh dùng số thập phân (dùng v1 thay vì v1.5)
  • Versioning sẽ được đặt ở vị trí đầu tiên của resource

Ví dụ:

  • https://example.org/api/v1/*
  • https://api.example.com/v1/*

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.

Phân trang

Xem sét cách lấy 25 phần tử từ vị trí thứ 50 của 3 hệ thống sau:

  • Facebook: offset 50 and limit 25
  • Twitter: page 3 and rpp 25 (records per page)
  • LinkedIn: start 50 and count 25

Trong trường hợp này, mình thiên về cách sử dung của facebook vì nó trực quan và dễ hiểu hơn. Ngoài ra, những bạn nào đã code database thì khái niệm “limit” và “offset” cũng không phải là một khái niệm gì mới.

Tìm kiếm

Quy tắc: attribute tên là “q”(query)

-Global search:

  • GET /search?q=fluffy+fur

-Scope search:

  • GET /users/123/cars?q=fluffy+fur

Sắp xếp fields

Cho phép sắp xếp tăng dần và giảm dần theo field cụ thể.

  • GET /cars?sort=-manufactorer,+model
    • +: Sắp xếp tăng dần
    • -: Sắp xếp giảm dần

Lựa chọn field trả về

Trong một số trường hợp, client sẽ không cần đầy đủ thông tin của một object. Ví dụ như phiên bản mobile sẽ không lấy hết thông tin của user như phiên bản web. Chính vì vậy chúng ta cần resource có khả năng tuỳ chỉnh những field trả về. Việc này làm tăng performance cho phía client.

  • GET /users?fields=id,name,address

Định dạng dữ liệu trả về

Đối với những resource hỗ trợ nhiều định dạng dữ liệu trả về, HTTP-Header sẽ là nơi để xác định dịnh dạng đó.

  • Content-Type: Khai báo request format
  • Accept: Khai báo response format

HTTP status code và error message

Chuẩn HTTP cung cấp cho ta rất nhiều status code. Chúng ta sẽ không cần biết hết tất cả nhưng ít nhất nên biết đến những 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

Đối với error message trả về khi có lỗi xảy ra cần đảm báo dễ hiểu cho cả user, client developer và backend developer. Về cơ bản chúng ta sẽ có 3 message trả về phục vụ cho 3 đối tượng khác nhau:

  • user message (message trả về cho user)
  • internal message (message trả vể cho backend developer)
  • code (message trả về cho client developer)

Một message đầy đủ yêu cầu sẽ có dạng như sau:

{
    "error":{
        "userMessage": "Sorry, the requested resource does not exist",
        "internalMessage": "No car found in the database",
        "code":34
    }
}

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. Chúc bạn thành công!

Cùng học lập trình tại: https://hoclaptrinh.me

Written by AnonyHome
Fullstack Developer ! Profile

Leave a Reply

Your email address will not be published. Required fields are marked *

ĐĂNG KÝ KHÓA HỌC JAVA CƠ BẢN
Đăng ký tham gia khóa học Java cơ bản Online. Học lập trình cùng AnonyHome
HỢP TÁC CÙNG CHÚNG TÔI
Chúng tôi nhận thực hiện các dự án:
  1. Phát triển ứng dụng Mobile
  2. Xây dựng website
  3. Đồ án sinh viên, luận văn thạc sĩ
  4. ..v.v
Mọi dự án đều được xây dựng với chi phí hợp lý.
Tham gia group Facebook: click here
Hợp tác phát triển các nền tảng ứng dụng
Chúng tôi nhận các dự án:
  1. Phát triển ứng dụng Mobile
  2. Xây dựng website
  3. Đồ án sinh viên, luận văn thạc sĩ