Khi xây dựng API RESTful, việc cập nhật các tài nguyên hiện có là một điều phổ biến mà ai cũng thường làm. Hai phương thức HTTP thường được sử dụng cho mục đích này bao gồm PUT và PATCH. Mặc dù cả hai đều được sử dụng để sửa đổi dữ liệu, nhưng chúng phục vụ các chức năng riêng biệt mà không phải ai cũng nắm rõ.
Bài viết này sẽ đi sâu vào những khác biệt chính giữa yêu cầu PUT và PATCH, cùng với đó là cung cấp các ví dụ và hướng dẫn rõ ràng để giúp bạn có thể lựa chọn phương pháp phù hợp cho API của mình.
Hiểu về yêu cầu PUT
1. Định nghĩa của PUT
Yêu cầu PUT được sử dụng để cập nhật hoặc tạo tài nguyên trên máy chủ. Hãy nghĩ đơn giản như việc thay thế toàn bộ một thứ bằng một phiên bản mới hơn của nó. Yêu cầu bao gồm toàn bộ representation của tài nguyên và máy chủ hiện có phải được thay thế bằng tài nguyên được cung cấp trong yêu cầu.
2. Tính bất biến và tính an toàn của PUT
- Idempotent : Yêu cầu PUT là idempotent, nghĩa là bạn có thể gửi nhiều lần và nó sẽ có hiệu ứng giống như gửi một lần. Ví dụ, nếu bạn cập nhật hồ sơ người dùng với cùng thông tin hai lần, kết quả sẽ giống như cập nhật một lần.
- An toàn : Yêu cầu PUT không được coi là an toàn. Nó sửa đổi dữ liệu trên máy chủ, do đó có khả năng gây ra tác dụng phụ.
3. Các trường hợp sử dụng cho PUT
- Tạo tài nguyên : Nếu tài nguyên không tồn tại, yêu cầu PUT có thể tạo tài nguyên đó.
- Thay thế toàn bộ tài nguyên : Nếu tài nguyên đã tồn tại, yêu cầu PUT sẽ thay thế tài nguyên đó bằng biểu diễn mới được gửi trong nội dung yêu cầu.
4. Ví dụ về yêu cầu PUT
Ví dụ JSON: Hãy tưởng tượng bạn có một tài nguyên người dùng với cấu trúc sau:
<font style="vertical-align: inherit;"><font style="vertical-align: inherit;">{</font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;"> "mã số": 1,</font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;"> "tên": "John Doe",</font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;"> "email": "johndoe@example.com"</font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;">
}</font></font><font></font>
Để cập nhật toàn bộ tài nguyên người dùng, bạn sẽ gửi yêu cầu PUT với dữ liệu người dùng đã cập nhật trong nội dung yêu cầu:
<font style="vertical-align: inherit;"><font style="vertical-align: inherit;">ĐẶT /người dùng/1 HTTP/1.1</font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;">
Loại nội dung: ứng dụng/json</font></font><font></font>
<font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;">
{</font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;"> "mã số": 1,</font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;"> "tên": "Jane Doe",</font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;"> "email": "janedoe@example.com"</font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;">
}</font></font><font></font>
Ví dụ XML: Đối với XML, cấu trúc sẽ tương tự như sau:
<font style="vertical-align: inherit;"><font style="vertical-align: inherit;">ĐẶT /người dùng/1 HTTP/1.1</font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;">
Loại nội dung: ứng dụng/xml</font></font><font></font>
<font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;">
<người dùng></font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;"> <id>1</id></font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;"> <tên>Jane Doe</tên></font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;"> <email>janedoe@example.com</email></font></font><font></font><font style="vertical-align: inherit;"><font style="vertical-align: inherit;">
</người dùng></font></font><font></font>
Định dạng cụ thể (JSON hoặc XML) phụ thuộc vào loại nội dung được chỉ định trong Content-Typetiêu đề.
Hiểu về yêu cầu PATCH
1. Định nghĩa của PATCH
Không giống như PUT, yêu cầu PATCH được sử dụng để áp dụng các sửa đổi một phần cho một tài nguyên. Thay vì thay thế toàn bộ tài nguyên, nó chỉ định các thay đổi cho các thuộc tính cụ thể.
2. Cập nhật một phần với PATCH
Với PATCH, bạn chỉ có thể sửa đổi các trường bạn muốn thay đổi. Điều này hữu ích khi bạn muốn cập nhật một phần nhỏ của tài nguyên mà không ảnh hưởng đến toàn bộ dữ liệu.
3. Các trường hợp sử dụng cho PATCH
- Cập nhật các trường cụ thể : Chỉ sửa đổi một số thuộc tính nhất định của tài nguyên, giữ nguyên các thuộc tính khác.
- Cập nhật gia tăng : Áp dụng các thay đổi dần dần, mà không thay thế toàn bộ tài nguyên.
4. Ví dụ về Yêu cầu PATCH
Có nhiều định dạng khác nhau cho yêu cầu PATCH, nhưng chúng tôi sẽ tập trung vào JSON Patch, được định nghĩa trong RFC 6902.
Ví dụ về bản vá JSON: Hãy tưởng tượng bạn muốn đổi tên người dùng thành “Jane Smith” và tăng tuổi của họ lên 1. Bạn sẽ gửi yêu cầu PATCH với tài liệu JSON Patch sau:
PATCH /users/1 HTTP/1.1<font></font>
Content-Type: application/json<font></font>
<font></font>
[<font></font> {"op": "replace", "path": "/name", "value": "Jane Smith"},<font></font> {"op": "add", "path": "/age", "value": 1}<font></font>
]<font></font>
Ví dụ này trình bày cách sử dụng hoạt động JSON Patch để sửa đổi các phần cụ thể của tài nguyên.
Khi nào sử dụng PUT so với PATCH?
Việc lựa chọn giữa PUT và PATCH phụ thuộc vào kết quả mong muốn của yêu cầu.
1. Hướng dẫn chung
- Sử dụng PUT khi bạn muốn thay thế toàn bộ tài nguyên bằng phiên bản mới.
- Sử dụng PATCH khi bạn muốn sửa đổi các phần cụ thể của tài nguyên mà không cần thay thế toàn bộ.
2. Những cân nhắc
- Tính bất biến: Nếu thao tác cần có tính bất biến (tạo ra cùng một kết quả bất kể số lần thực hiện), thì PUT thường được ưu tiên hơn.
- Truyền dữ liệu: Nếu bạn đang gửi một lượng lớn dữ liệu, PATCH có thể hiệu quả hơn vì nó chỉ gửi các phần đã thay đổi.
- Thiết kế API: Xem xét thiết kế tổng thể của API và cách các phương pháp này phù hợp với mô hình tài nguyên của bạn.
3. Ví dụ
Cập nhật hồ sơ người dùng:
- Nếu bạn muốn thay thế toàn bộ thông tin người dùng, hãy sử dụng PUT.
- Nếu bạn chỉ muốn thay đổi địa chỉ email của người dùng, hãy sử dụng PATCH. Cập nhật sản phẩm:
- Nếu bạn muốn thay thế toàn bộ sản phẩm bằng phiên bản mới, hãy sử dụng PUT.
- Nếu bạn muốn thay đổi giá hoặc mô tả sản phẩm, hãy sử dụng PATCH.
Dưới đây tôi sẽ trình bày các trường hợp kịch bản dưới dạng bảng để tham khảo tốt hơn
Kết luận
Nắm vững các trạng thái của PUT và PATCH chính là nền tảng để tạo ra các API RESTful trực quan và hiệu quả nhất. Bằng cách hiểu mục đích riêng biệt của chúng và áp dụng chúng một cách khôn ngoan, bạn có thể cải thiện đáng kể trải nghiệm người dùng và nâng cao khả năng bảo trì các ứng dụng của mình.
Mặc dù việc lựa chọn giữa PUT và PATCH có vẻ đơn giản, nhưng những điều tinh tế liên quan có thể tạo ra tác động đáng kể đến hành vi của API. Tôi hy vọng rằng hướng dẫn này đã trang bị cho bạn kiến thức để tự tin lựa chọn phương pháp phù hợp cho các trường hợp sử dụng cụ thể của mình. Cảm ơn các bạn đã theo dõi.