Đây là bài viêt đầu tiên trong chuỗi bài về xây dựng một hệ thống Backend theo mô hình Micoservices sử dụng Spring Boot và triển khai trên Kubernetes.

Kiến thức không có gì mới, chỉ là tóm tắt lại một số nguyên tắc chung trong việc thiết kế RESTful APIs, nó cũng là nguyên tắc chung cho việc thiết kết các APIs trong các ví dụ mẫu của bài viết

HTTP Methods/Verbs

• GET được sử dụng để request dữ liệu từ một nguồn dữ liệu cụ thể.
• POST được sử dụng để gửi dữ liệu tới một server để tạo hoặc cập nhật tài nguyên trên đó
• PUT được sử dụng để gửi dữ liệu tới server để tạo hoặc cập nhật tài nguyên trên đó
• HEAD gần giống giống với lại GET, tuy nhiên nó không có response body. Dùng để kiểm tra trước khi gọi GET
• DELETE được sử dụng để xóa tài nguyên cụ thể nào đó.
• PATCH dùng để cập nhật một thuộc tính của tài nguyên.
• OPTIONS được sử dụng để mô tả các tùy chọn trong quá trình giao tiếp cho tài nguyên đích.

Nguyên tắc thiết kế

• Hành động trong CRUD sử dụng các HTTP Methods tương ứng
  • 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.

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

- GET /employees
- GET /employees/{id}
- PUT /employee{id}
- POST /employees
- PATH /employee{id}
- DELETE /employee{id}

- GET /employees
- GET /employees/{id}
- PUT /employee{id}
- POST /employees
- PATH /employee{id}
- DELETE /employee{id}

• KHÔNG sử dụng động từ cho việc thiết kế API

GET /getAllEmployee
GET /getDetailEmployee

• Tên API là chữ thường, với tên dài sử dụng dấu gạch ngang (-) để thể hiện ý nghĩa rõ ràng hơn

- GET /managed-devices

- GET /managed-devices

• API phải thể thiện được cấu trúc quan hệ. Giả sử thực thể Nhân viên (employee) có quản lý các Thiết bị (device). Khi thiết kế API cần thể hiện được quan hệ của thực thể này

GET /employees/{id}/devices hiển thị toàn bộ thiết bị mà nhân viên đó quản lý
GET /employees/{id}/devices/{deviceId} lấy thông tin chi tiết của thiết bị có id là deviceId mà nhân viên có id quản lý
POST /employees/{id}/devices thêm thiết bị cho nhân viên

GET /employees/{id}/devices hiển thị toàn bộ thiết bị mà nhân viên đó quản lý
GET /employees/{id}/devices/{deviceId} lấy thông tin chi tiết của thiết bị có id là deviceId mà nhân viên có id quản lý
POST /employees/{id}/devices thêm thiết bị cho nhân viên

• Sử dụng version để quản lý phiên bản của API

- /v1/dogoo/employees
- /v2/dogoo/employees

- /v1/dogoo/employees
- /v2/dogoo/employees

• Mã trạng thái, mã lỗi rõ ràng

200 - OK - Eyerything is working
201 - Created - A new resource has been created
304 - Not Modified - The client can use cached data
400 - Bad Request - The request was invalid or cannot be served. The exact error should be explained in the error payload. E.g. "The JSON is not valid"
401 - Unauthorized - The request requires an user authentication
403 - Forbidden -The server understood the request, but is refusing it or the access is not allowed.
404 - Not found - There is no resource behind the URI.
422 - Unprocessable Entity - Should be used if the server cannot process the enitity, e.g. if an image cannot be formatted or mandatory fields are missing in the payload.
429 - Too Many Requests - The user has sent too many requests in a given amount of time ("rate limiting").
500 - Internal Server Error - API developers should avoid this error. If an error occurs in the global catch blog, the stracktrace should be logged and not returned as response

200 - OK - Eyerything is working
201 - Created - A new resource has been created
304 - Not Modified - The client can use cached data
400 - Bad Request - The request was invalid or cannot be served. The exact error should be explained in the error payload. E.g. "The JSON is not valid"
401 - Unauthorized - The request requires an user authentication
403 - Forbidden -The server understood the request, but is refusing it or the access is not allowed.
404 - Not found - There is no resource behind the URI.
422 - Unprocessable Entity - Should be used if the server cannot process the enitity, e.g. if an image cannot be formatted or mandatory fields are missing in the payload.
429 - Too Many Requests - The user has sent too many requests in a given amount of time ("rate limiting").
500 - Internal Server Error - API developers should avoid this error. If an error occurs in the global catch blog, the stracktrace should be logged and not returned as response

• Khi có lỗi trả về chi tiết Error Response Body

{
   "status": 401,
   "code": "DOGOO-100",
   "message": "string",
   "developerMessage": "string"
}

{
   "status": 401,
   "code": "DOGOO-100",
   "message": "string",
   "developerMessage": "string"
}

Khi sử dụng Spring Boot, khuyến khích sử dụng ProblemDetail để thể hiện chi tiết lỗi

• Tài liệu rõ ràng, một số ngôn ngữ dùng để mô tả tài liệu cho RESTful APIs
  • Swagger/OpenAPI
  • Redoc
  • Postman

Tổng kết

Hiểu về nguyên tắc thiết kế RESTful APIs giúp chúng ta dễ dàng tiếp cận tài liệu tích hợp các hệ thống cũng như giúp chúng ta có thể thiết kế API trong hệ thống của mình một cách rõ ràng, chuẩn mực hơn!