Một số lưu ý khi viết RESTFul API

nvlam -

Đối với các lập trình viên ngày này thì việc tiếp xúc và làm việc với Api đã không còn quá mới mẻ. Api có thể giúp chúng ta kết nối nhiều hệ thống với nhau, có thể cung cấp dữ liệu để xây dựng các chương trình với nhiều nền tảng. Vậy bạn có bao giờ thắc mắc Api là gì? Hay thiết kế Api như thế nào cho đúng không?

Hôm nay mình xin chia sẻ cho các bạn một số kiến thức liên quan đến Api và một số nguyên tắc thiết kế RESTFul API.

Bài viết gồm có 2 phần:

  • Api là gì?
  • Một số lưu ý khi thết kế RESTFul API

1. Api là gì?

Api - Application Programming Interface bạn có thể hiểu nó là giao diện lập trình ứng dụng, nó như là cách thức hay phương thức để kết nối các thư viện, các ứng dụng lại với nhau cho phép chúng có thể chia sẻ dữ liệu qua lại một cách dễ dàng.

Chúng ta thường gặp các Api trong các ứng dụng Web Api dùng để cung cấp dữ liệu hoặc một số chức năng cho hệ thống khác tiêu biểu như các tính năng đăng nhập của Facebook, Google,... để có thể tích hợp được các tính năng đó thì bạn phải gọi đến Api mà dịch vụ thứ 3 cung cấp sẵn ở đây là Facebook và Google. Api còn được ứng dụng trong các hệ điều hành, trên một số thư viện hay Framework có sẵn.

Còn RESTFul API là gì? Đầu tiên thì nó không phải là một công nghệ hay một thư viện, RESTFul API đơn giản chỉ là một tập các nguyên tắc, các tiêu chuẩn đề ra để lập trình viên có thể tuân thủ và tạo ra một sự thống nhất trong thiết kế. RESTFul API thường chú trọng vào các tài nguyên trong hệ thống, phân chia rõ ràng các hành động đối với dữ liệu.

2. Một số lưu ý khi thiết RESTFul API

  • Dữ liệu trả về: Thường có 3 phần(data, messages, status_code - có thể có hoặc không)
message : 'Success',
    data : {
        'user' : {
            id: 1,
            name: 'Haposoft',
            ...
        },
        ...
    }
  • Một số status_code quan trong:
Action Create success : 201
Action Read success : 200
Action Update success : 200
Action Delete success : 200
Bad Request : 400
Unauthorized : 401
Forbidden : 403
Not Found : 404
Method Not Allowed : 405
Internal Server Error : 500
Not Implemented : 501
Bad Gateway : 502
Service Unavailable : 503
Gateway Timeout : 504
  • Sử dụng các danh từ số nhiều thay cho động từ
GOOD
GET: /posts
POST: /posts
PUT: /posts/{id}
DELETE: /posts/{id}
BAD
GET: /getPosts
POST: /createPosts
PUT: /updatePosts/{id}
DELETE: /deletePosts/{id}
  • Liên kết trong resource: Thường liên kết tối đa 2 object
GOOD
/stores/{id}/posts/{id}?comments={id}
BAD
/stores/{id}/posts/{id}/comments={id}
  • Không nên sử dụng '_'
GOOD
/stores/{id}/posts/{id}?comments-pro={id}
BAD
/stores/{id}/posts/{id}?comments_pro={id}
  • Các dữ liệu nên được tranform khi trả về
  • Sắp xếp các field
+: Sắp xếp tăng dần (/posts?sort=+date)
- : Sắp xếp giảm dần  (/post?sort=-name)
  • Sử dụng các phương thức cho từng mục đích khác nhau:
GET: Chỉ để lấy dữ liệu
POST: Thêm dữ liệu
PUT/PATCH: Cập nhập dữ liêu
DELETE: Xóa dữ liệu
  • Nên có các cơ chế xác thực và xác minh
Http basic, JWT, Oauth2,...
  • Version Api
Nếu có nhiều version khác nhau nên viết: /v1/posts, /v2/posts,...
  • Cần có Api document
Viết mô tả ra file
Dùng thư viện bên thứ 3: laravel-apidoc-generator, swagger,...

Bài viết của mình đến đây là hết, hi vọng nó hữu ích cho mọi người!!!