Triển khai mẫu lệnh trong API RESTful

Tôi đang trong quá trình thiết kế API HTTP, hy vọng làm cho nó trở nên RESTful nhất có thể.

Có một số hành động mà chức năng trải rộng trên một vài tài nguyên và đôi khi cần phải hoàn tác.

Tôi tự nghĩ, điều này nghe giống như một mẫu lệnh, nhưng làm thế nào tôi có thể mô hình hóa nó thành một tài nguyên?

Tôi sẽ giới thiệu một tài nguyên mới có tên XXAction, như DepositAction, sẽ được tạo thông qua một cái gì đó như thế này

POST /card/{card-id}/account/{account-id}/Deposit
AmountToDeposit=100, different parameters...

điều này thực sự sẽ tạo một DepositAction mới và kích hoạt phương thức Do / Execute. Trong trường hợp này, trả về trạng thái HTTP được tạo 201 có nghĩa là hành động đã được thực hiện thành công.

Sau này nếu khách hàng muốn xem chi tiết hành động anh ta có thể

GET /action/{action-id}

Tôi đoán cập nhật / PUT sẽ bị chặn, vì nó không liên quan ở đây.

Và để hoàn tác hành động, tôi nghĩ đến việc sử dụng

DELETE /action/{action-id}

mà thực sự sẽ gọi phương thức Hoàn tác của đối tượng có liên quan và thay đổi trạng thái của nó.

Hãy nói rằng tôi hạnh phúc chỉ với một Do-Undo, tôi không cần Làm lại.

Cách tiếp cận này có ổn không?

Có bất kỳ cạm bẫy, lý do không sử dụng nó?

Điều này có được hiểu từ POV của khách hàng không?

Bạn đang thêm vào một lớp trừu tượng gây nhầm lẫn

API của bạn bắt đầu rất sạch sẽ và đơn giản. POST HTTP tạo một tài nguyên Tiền gửi mới với các tham số đã cho. Sau đó, bạn đi ra khỏi đường ray bằng cách giới thiệu ý tưởng về "hành động" là một chi tiết triển khai chứ không phải là một phần cốt lõi của API.

Thay vào đó, hãy xem xét cuộc trò chuyện HTTP này ...

POST / thẻ / {card-id} / tài khoản / {tài khoản-id} / Gửi tiền

Số lượng ToDeposit = 100, các tham số khác nhau ...

201 TẠO

Vị trí = / thẻ / 123 / tài khoản / 456 / Tiền gửi / 789

Bây giờ bạn muốn hoàn tác thao tác này (về mặt kỹ thuật không nên cho phép điều này trong một hệ thống kế toán cân bằng nhưng điều này là gì):

XÓA / thẻ / 123 / tài khoản / 456 / Tiền gửi / 789

204 KHÔNG CÓ NỘI DUNG

Người tiêu dùng API biết rằng họ đang xử lý tài nguyên Tiền gửi và có thể xác định những hoạt động nào được phép trên đó (thường thông qua TÙY CHỌN trong HTTP).

Mặc dù việc triển khai thao tác xóa được thực hiện thông qua "hành động" ngày nay, không có gì đảm bảo rằng khi bạn di chuyển hệ thống này từ, giả sử, C # sang Haskell và duy trì mặt trước rằng khái niệm phụ về "hành động" sẽ tiếp tục tăng giá trị , trong khi khái niệm chính về Tiền gửi chắc chắn có.

Chỉnh sửa để bao gồm một giải pháp thay thế cho XÓA và Gửi tiền

Để tránh thao tác xóa nhưng vẫn xóa hiệu quả Khoản tiền gửi, bạn nên thực hiện các thao tác sau (sử dụng Giao dịch chung để cho phép Gửi tiền và rút tiền):

POST / thẻ / {card-id} / tài khoản / {tài khoản-id} / Giao dịch

Số tiền = -100 , các thông số khác nhau ...

201 TẠO

Vị trí = / thẻ / 123 / tài khoản / 456 / Chuyển đổi / 790

Tài nguyên Giao dịch mới được tạo có số tiền chính xác (-100). Điều này có tác dụng cân bằng tài khoản về 0, phủ nhận Giao dịch gốc.

Bạn có thể xem xét việc tạo điểm cuối "tiện ích" như

POST / thẻ / {card-id} / tài khoản / {tài khoản-id} / Giao dịch / 789 / Hoàn tác <- BAD!

để có được hiệu quả tương tự. Tuy nhiên, điều này phá vỡ ngữ nghĩa của một URI như là một định danh bằng cách giới thiệu một động từ. Bạn tốt hơn hết là bám vào các danh từ trong định danh và giữ cho các hoạt động bị ràng buộc với các động từ HTTP. Bằng cách đó, bạn có thể dễ dàng tạo một permalink từ mã định danh và sử dụng nó cho GET và vv.

Lý do chính cho sự tồn tại của REST là khả năng phục hồi chống lại các lỗi mạng. Để kết thúc tất cả các hoạt động nên idempotent .

Cách tiếp cận cơ bản có vẻ hợp lý, nhưng cách bạn mô tả DepositActionsáng tạo không có vẻ gì là bình thường, cần được sửa chữa. Bằng cách khách hàng cung cấp ID duy nhất sẽ được sử dụng để phát hiện các yêu cầu trùng lặp. Vì vậy, sự sáng tạo sẽ thay đổi thành

PUT /card/{card-id}/account/{account-id}/Deposit/{action-id}
AmountToDeposit=100, different parameters...

Nếu một PUT khác cho cùng một URL được thực hiện với cùng một nội dung như trước đó, thì phản hồi vẫn phải là 201 created nếu nội dung giống nhau và lỗi nếu nội dung khác nhau. Điều này cho phép khách hàng chỉ cần truyền lại yêu cầu khi không thành công, vì khách hàng không thể biết liệu yêu cầu hoặc phản hồi có bị mất hay không.

Nó có ý nghĩa hơn khi sử dụng PUT, bởi vì nó chỉ ghi tài nguyên và không có gì, nhưng sử dụng POST cũng không thực sự gây ra bất kỳ vấn đề nào.

Để xem chi tiết giao dịch, khách hàng sẽ GETsử dụng cùng một URL, nghĩa là

GET /card/{card-id}/account/{account-id}/Deposit/{action-id}

và để hoàn tác nó, nó có thể XÓA nó. Nhưng nếu nó thực sự có liên quan đến tiền như mẫu gợi ý, tôi sẽ đề nghị PUTting nó với các cờ "bị hủy" thay vì trách nhiệm giải trình (rằng vẫn còn dấu vết của giao dịch được tạo và hủy).

Bây giờ bạn cần chọn một phương thức tạo id duy nhất. Bạn có một vài lựa chọn:

1. Phát hành tiền tố dành riêng cho khách hàng trước đó trong quá trình trao đổi phải được đưa vào.
2. Thêm một yêu cầu POST đặc biệt để nhận ID duy nhất trống từ máy chủ. Yêu cầu này không phải là bình thường (và thực sự không thể), vì ID không được sử dụng không thực sự gây ra bất kỳ rắc rối nào.
3. Đơn giản chỉ cần sử dụng UUID. Mọi người đều sử dụng chúng và dường như không ai có vấn đề gì với cả những người dựa trên MAC cũng như những người ngẫu nhiên.