Trong bài viết này tác giả tuyên bố rằng

Đôi khi, cần phải hiển thị một hoạt động trong API vốn không phải là RESTful.

và đó

Nếu một API có quá nhiều hành động, thì đó là một dấu hiệu cho thấy nó được thiết kế với quan điểm RPC thay vì sử dụng các nguyên tắc RESTful hoặc API được đề cập tự nhiên phù hợp hơn với mô hình loại RPC.

Điều này phản ánh những gì tôi đã đọc và nghe ở nơi khác là tốt.

Tuy nhiên tôi thấy điều này khá khó hiểu và tôi muốn hiểu rõ hơn về vấn đề này.

Ví dụ I: Tắt VM thông qua giao diện REST

Tôi nghĩ, có hai cách khác nhau cơ bản để mô hình hóa việc tắt máy ảo. Mỗi cách có thể có một vài biến thể, nhưng bây giờ hãy tập trung vào những khác biệt cơ bản nhất.

1. Vá tài sản nhà nước của tài nguyên

PATCH /api/virtualmachines/42
Content-Type:application/json  

{ "state": "shutting down" }

(Ngoài ra, PUTtrên tài nguyên phụ /api/virtualmachines/42/state.)

VM sẽ tắt trong nền và tại một thời điểm nào đó sau đó tùy thuộc vào việc tắt thời gian sẽ thành công hay không trạng thái có thể được cập nhật nội bộ với "tắt nguồn".

2. PUT hoặc POST trên thuộc tính hành động của tài nguyên

PUT /api/virtualmachines/42/actions
Content-Type:application/json  

{ "type": "shutdown" }

Kết quả hoàn toàn giống như trong ví dụ đầu tiên. Trạng thái sẽ được cập nhật để "tắt" ngay lập tức và cuối cùng có thể "tắt nguồn".

Cả hai thiết kế RESTful?

Thiết kế nào tốt hơn?

Ví dụ II: CQRS

Điều gì xảy ra nếu chúng ta có một miền CQRS với nhiều "hành động" (còn gọi là các lệnh) có khả năng dẫn đến cập nhật nhiều tập hợp hoặc không thể ánh xạ tới các hoạt động CRUD trên tài nguyên cụ thể và tài nguyên phụ?

Chúng ta có nên cố gắng mô hình hóa nhiều lệnh như cụ thể tạo hoặc cập nhật trên các tài nguyên cụ thể, ở đâu có thể (theo cách tiếp cận đầu tiên từ ví dụ I) và sử dụng "điểm cuối hành động" cho phần còn lại không?

Hoặc chúng ta nên ánh xạ tất cả các lệnh đến các điểm cuối hành động (như trong cách tiếp cận thứ hai của ví dụ I)?

Chúng ta nên vẽ đường thẳng ở đâu? Khi nào thiết kế trở nên ít RESTful?

Mô hình CQRS có phù hợp hơn với RPC như API không?

Theo các văn bản trích dẫn ở trên, như tôi hiểu nó.

Như bạn có thể thấy từ nhiều câu hỏi của tôi, tôi hơi bối rối về chủ đề này. Bạn có thể giúp tôi hiểu rõ hơn về nó?

Trong trường hợp đầu tiên (tắt máy ảo), tôi sẽ không xem xét bất kỳ lựa chọn thay thế nào của OP RESTful. Cấp, nếu bạn sử dụng mô hình trưởng thành của Richardson làm thước đo, cả hai đều là API 2 vì chúng sử dụng tài nguyên và động từ.

Mặc dù vậy, cả hai đều không sử dụng các điều khiển hypermedia và theo tôi, đó là loại REST duy nhất phân biệt thiết kế API RESTful với RPC. Nói cách khác, hãy gắn bó với cấp 1 và 2 và bạn sẽ có API kiểu RPC trong hầu hết các trường hợp.

Để mô hình hóa hai cách khác nhau để tắt VM, tôi đã phơi bày chính VM như một tài nguyên (trong số những thứ khác) có chứa các liên kết:

{
    "links": [{
        "rel": "shut-down",
        "href": "/vms/1234/fdaIX"
    }, {
        "rel": "power-off",
        "href": "/vms/1234/CHTY91"
    }],
    "name": "Ploeh",
    "started": "2016-08-21T12:34:23Z"
}

Nếu một máy khách muốn tắt PloehVM, nó phải theo liên kết với shut-downloại mối quan hệ. (Thông thường, như được nêu trong Sổ tay dịch vụ web RESTful , bạn sẽ sử dụng IRI hoặc sơ đồ nhận dạng phức tạp hơn cho các loại mối quan hệ, nhưng tôi đã chọn giữ ví dụ đơn giản nhất có thể.)

Trong trường hợp này, có rất ít thông tin khác để cung cấp cho hành động, vì vậy khách hàng nên đơn giản tạo một POST trống đối với URL trong href:

POST /vms/1234/fdaIX HTTP/1.1

(Vì yêu cầu này không có nội dung, nên sẽ mô hình hóa yêu cầu này thành yêu cầu GET, nhưng các yêu cầu GET không có tác dụng phụ có thể quan sát được, vì vậy POST đúng hơn.)

Tương tự, nếu khách hàng muốn tắt nguồn VM, power-offthay vào đó , nó sẽ theo liên kết.

Nói cách khác, các loại mối quan hệ của các liên kết cung cấp khả năng chi trả cho thấy ý định. Mỗi loại mối quan hệ có một ý nghĩa ngữ nghĩa cụ thể. Đây là lý do đôi khi chúng ta nói về web ngữ nghĩa .

Để giữ cho ví dụ rõ ràng nhất có thể, tôi cố tình che khuất các URL trong mỗi liên kết. Khi máy chủ lưu trữ nhận được yêu cầu đến, nó sẽ biết điều đó fdaIXcó nghĩa là tắt và CHTY91có nghĩa là tắt nguồn .

Thông thường, tôi chỉ mã hóa hành động trong chính URL, để các URL sẽ /vms/1234/shut-downvà /vms/1234/power-off, nhưng khi giảng dạy, điều đó làm mờ sự khác biệt giữa các loại mối quan hệ (ngữ nghĩa) và URL (chi tiết triển khai).

Tùy thuộc vào ứng dụng khách nào bạn có, bạn có thể xem xét làm cho các URL RESTful không bị hack .

CQRS

Khi nói đến CQRS, một trong số ít những điều mà Greg Young và Udi Dahan đồng ý là CQRS không phải là một kiến ​​trúc cấp cao nhất . Do đó, tôi nên thận trọng khi tạo API RESTful giống CQRS, vì điều đó có nghĩa là các máy khách trở thành một phần trong kiến ​​trúc của bạn.

Thông thường, động lực đằng sau API RESTful (cấp 3) thực sự là bạn muốn có thể phát triển API của mình mà không phá vỡ ứng dụng khách và không có quyền kiểm soát khách hàng. Nếu đó là động lực của bạn, thì CQRS sẽ không phải là lựa chọn đầu tiên của tôi.

Tắt VM thông qua giao diện REST

Đây thực sự là một ví dụ nổi tiếng, được đưa ra bởi Tim Bray vào năm 2009 .

Roy Fielding, thảo luận về vấn đề, đã chia sẻ quan sát này :

Cá nhân tôi thích các hệ thống coi trạng thái giám sát (như trạng thái sức mạnh) là không thể chỉnh sửa.

Nói tóm lại, bạn có một tài nguyên thông tin trả về một đại diện hiện tại của trạng thái được giám sát; đại diện đó có thể bao gồm một liên kết hypermedia đến một biểu mẫu để yêu cầu thay đổi trạng thái đó và biểu mẫu có một liên kết khác đến một tài nguyên để xử lý (mỗi) yêu cầu thay đổi.

Seth Ladd đã có những hiểu biết quan trọng trong vấn đề

Chúng tôi đã biến Chạy từ trạng thái đơn giản của một người thành Danh từ thực sự có thể được tạo, cập nhật và nói chuyện.

Lấy lại điều này để khởi động lại máy. Tôi sẽ lập luận rằng bạn sẽ POST lên / vdc / 434 / cluster / 4894 / server / 4343 / khởi động lại Sau khi bạn đăng, bạn có một URI đại diện cho khởi động lại này và bạn có thể NHẬN nó để cập nhật trạng thái. Thông qua sự kỳ diệu của siêu liên kết, đại diện của Reboot được liên kết với Máy chủ được khởi động lại.

Tôi nghĩ rằng không gian đúc URI là rẻ, và URI thậm chí còn rẻ hơn. Tạo một tập hợp các hoạt động, được mô hình hóa dưới dạng Danh từ và POST, PUT và XÓA đi!

Lập trình RESTful là bộ máy quan liêu Vogon ở quy mô web. Làm thế nào để bạn làm bất cứ điều gì RESTful? Phát minh ra giấy tờ mới cho nó, và số hóa giấy tờ.

Trong ngôn ngữ có phần khó hiểu hơn, những gì bạn đang làm là xác định giao thức ứng dụng miền cho "tắt máy ảo" và xác định các tài nguyên mà bạn cần để lộ / thực hiện giao thức đó

Nhìn vào ví dụ của riêng bạn

PATCH /api/virtualmachines/42
Content-Type:application/json  

{ "state": "shutting down" }

Vậy là được rồi; bạn không thực sự coi yêu cầu đó là tài nguyên thông tin riêng biệt của mình, nhưng bạn vẫn có thể quản lý.

Bạn đã bỏ lỡ một chút trong đại diện của bạn về sự thay đổi.

Tuy nhiên, với PATCH, thực thể kèm theo chứa một tập hợp các hướng dẫn mô tả cách tài nguyên hiện đang cư trú trên máy chủ gốc nên được sửa đổi để tạo ra một phiên bản mới.

Ví dụ: hướng dẫn định dạng loại phương tiện Patch Patch như thể bạn đang trực tiếp sửa đổi tài liệu JSON

[
    { "op": "replace", "path": "state", "value": "shutting down" }
]

Trong lựa chọn của bạn, ý tưởng là gần, nhưng không rõ ràng chính xác. PUTlà một sự thay thế hoàn toàn trạng thái của tài nguyên tại URL mục tiêu , vì vậy bạn có thể sẽ không chọn một cách viết mà trông giống như một bộ sưu tập như là mục tiêu của một đại diện của một đơn thực thể.

POST /api/virtualmachines/42/actions

Phù hợp với giả tưởng rằng chúng tôi đang nối thêm một hành động vào hàng đợi

PUT /api/virtualmachines/42/latestAction

Phù hợp với giả tưởng rằng chúng tôi đang thực hiện cập nhật cho mục đuôi trong hàng đợi; Làm điều này hơi lạ một chút. Nguyên tắc ít ngạc nhiên nhất khuyên bạn nên cung cấp cho mỗi PUT đó là định danh duy nhất của riêng mình, thay vì đặt tất cả chúng vào một nơi và sửa đổi nhiều tài nguyên cùng một lúc.

Lưu ý rằng, cho đến nay chúng ta đang thảo luận về chính tả của URI - REST không quan tâm; /cc719e3a-c772-48ee-b0e6-09b4e7abbf8blà một URI hoàn hảo có liên quan đến REST. Khả năng đọc, như với tên biến, là một mối quan tâm riêng biệt. Sử dụng cách viết phù hợp với RFC 3986 sẽ khiến mọi người hạnh phúc hơn rất nhiều.

CQRS

Điều gì xảy ra nếu chúng ta có một miền CQRS với nhiều "hành động" (còn gọi là các lệnh) có khả năng dẫn đến cập nhật nhiều tập hợp hoặc không thể ánh xạ tới các hoạt động CRUD trên tài nguyên cụ thể và tài nguyên phụ?

Greg Young trên CQRS

CQRS là một mẫu rất đơn giản cho phép nhiều cơ hội cho kiến ​​trúc có thể không tồn tại. CQRS không phải là sự nhất quán cuối cùng, nó không phải là sự kiện, nó không phải là nhắn tin, nó không có các mô hình riêng biệt để đọc và viết, cũng không sử dụng nguồn sự kiện.

Khi hầu hết mọi người nói về CQRS, họ thực sự đang nói về việc áp dụng mẫu CQRS cho đối tượng đại diện cho ranh giới dịch vụ của ứng dụng.

Cho rằng bạn đang nói về CQRS trong bối cảnh HTTP / REST, có vẻ hợp lý khi cho rằng bạn đang làm việc trong bối cảnh sau này, vì vậy hãy đi với điều đó.

Điều này, đáng ngạc nhiên, thậm chí còn dễ dàng hơn so với ví dụ trước đây của bạn. Lý do cho điều này là đơn giản: các lệnh là tin nhắn .

Jim Webber mô tả HTTP là giao thức ứng dụng của văn phòng những năm 1950; công việc được thực hiện bằng cách lấy tin nhắn và đưa chúng vào hộp thư đến. Cùng một ý tưởng - chúng tôi nhận được một bản sao trống của một biểu mẫu, điền nó với các chi tiết cụ thể mà chúng tôi biết, cung cấp nó. Ta da

Chúng ta có nên cố gắng mô hình hóa nhiều lệnh như cụ thể tạo hoặc cập nhật trên các tài nguyên cụ thể, ở đâu có thể (theo cách tiếp cận đầu tiên từ ví dụ I) và sử dụng "điểm cuối hành động" cho phần còn lại không?

Đúng, trong chừng mực "tài nguyên cụ thể" là các thông điệp, chứ không phải là các thực thể trong mô hình miền.

Ý tưởng chính: API REST của bạn vẫn là một giao diện ; bạn sẽ có thể thay đổi mô hình cơ bản mà không cần khách hàng thay đổi tin nhắn. Khi bạn phát hành một mô hình mới, bạn phát hành một phiên bản mới của các điểm cuối web của bạn biết cách lấy giao thức miền của bạn và áp dụng nó cho mô hình mới.

Mô hình CQRS có phù hợp hơn với RPC như API không?

Không thực sự - đặc biệt, bộ nhớ cache web là một ví dụ tuyệt vời về "mô hình đọc cuối cùng nhất quán". Làm cho mỗi chế độ xem của bạn có thể truy cập độc lập, mỗi chế độ có quy tắc bộ đệm riêng, cung cấp cho bạn một loạt các tỷ lệ miễn phí. Có rất ít sự hấp dẫn đối với cách tiếp cận RPC dành riêng để đọc.

Đối với viết, đó là một câu hỏi khó hơn: gửi tất cả các lệnh đến một trình xử lý duy nhất tại một điểm cuối duy nhất hoặc một họ các điểm cuối, chắc chắn dễ dàng hơn . REST thực sự là nhiều hơn về cách bạn tìm thấy giao tiếp trong đó điểm cuối là máy khách.

Việc coi tin nhắn là tài nguyên duy nhất của riêng nó có lợi thế là bạn có thể sử dụng PUT, cảnh báo các thành phần trung gian về việc xử lý tin nhắn là không cần thiết, để chúng có thể tham gia vào một số trường hợp xử lý lỗi nhất định, là một điều tuyệt vời . (Lưu ý: theo quan điểm của khách hàng, nếu các tài nguyên có URI khác nhau, thì chúng là các tài nguyên khác nhau, thực tế là tất cả chúng đều có cùng mã xử lý yêu cầu trên máy chủ gốc là một chi tiết triển khai được ẩn bởi đồng phục giao diện).

Fielding (2008)

Tôi cũng cần lưu ý rằng phần trên chưa hoàn toàn RESTful, ít nhất là cách tôi sử dụng thuật ngữ này. Tất cả những gì tôi đã làm được mô tả các giao diện dịch vụ, không nhiều hơn bất kỳ RPC nào. Để làm cho RESTful, tôi cần thêm siêu văn bản để giới thiệu và xác định dịch vụ, mô tả cách thực hiện ánh xạ bằng các biểu mẫu và / hoặc mẫu liên kết và cung cấp mã để kết hợp trực quan hóa theo những cách hữu ích.

Bạn có thể tận dụng 5 cấp loại phương tiện để chỉ định lệnh trong trường tiêu đề loại nội dung của yêu cầu.

Trong ví dụ VM, nó sẽ là một cái gì đó dọc theo các dòng này

PUT /api/virtualmachines/42
Content-Type:application/json;domain-model=PowerOnVm

> HTTP/1.1 201 Created
Location: /api/virtualmachines/42/instance

Sau đó

DELETE /api/virtualmachines/42/instance
Content-Type:application/json;domain-model=ShutDownVm

Hoặc là

DELETE /api/virtualmachines/42/instance
Content-Type:application/json;domain-model=PowerOffVm

Xem https://www.infoq.com/articles/rest-api-on-cqrs

Ví dụ trong bài viết được liên kết dựa trên ý tưởng rằng khởi động máy và tắt máy phải được điều khiển bằng lệnh thay vì thay đổi trạng thái của tài nguyên được mô hình hóa. Thứ hai là khá nhiều những gì REST sống và thở. Mô hình hóa tốt hơn của VM đòi hỏi phải xem cách thức đối tác trong thế giới thực của nó hoạt động và cách bạn, như một con người, sẽ tương tác với nó như thế nào. Điều này là dài dòng, nhưng tôi nghĩ rằng nó cung cấp cái nhìn sâu sắc tốt về kiểu suy nghĩ cần thiết để làm mô hình tốt.

Có hai cách để kiểm soát trạng thái năng lượng của máy tính trên bàn của tôi:

• Công tắc nguồn: Ngay lập tức cắt dòng điện vào nguồn điện, khiến toàn bộ máy tính bị dừng đột ngột, mất trật tự.
• Nút bật / tắt: Nói với phần cứng để thông báo cho phần mềm rằng một cái gì đó ở bên ngoài muốn mọi thứ tắt. Phần mềm thực hiện tắt máy có trật tự, thông báo cho phần cứng đã hoàn thành và phần cứng báo hiệu nguồn điện mà nó có thể chuyển sang trạng thái chờ. Nếu công tắc nguồn được bật, máy đang chạy và phần mềm ở trạng thái không thể phản hồi tín hiệu tắt, hệ thống sẽ không tắt trừ khi tôi tắt công tắc nguồn. (Máy ảo sẽ hoạt động chính xác theo cùng một cách; nếu tín hiệu tắt máy bị phần mềm bỏ qua, máy sẽ tiếp tục chạy Tôi phải buộc nó tắt nguồn.) Nếu tôi muốn có thể khởi động lại máy, tôi phải bật lại công tắc nguồn và sau đó nhấn nút bật / tắt. (Nhiều máy tính có tùy chọn sử dụng một lần nhấn nút nguồn để chuyển trực tiếp sang trạng thái chờ, nhưng mô hình này không thực sự cần điều đó.) Nút này có thể được coi như một công tắc bật tắt vì nhấn nó sẽ dẫn đến hành vi khác nhau tùy thuộc vào trạng thái khi nhấn. Nếu công tắc nguồn bị tắt, nhấn nút này hoàn toàn không có gì.

Đối với VM, cả hai đều có thể được mô hình hóa thành các giá trị Boolean đọc / ghi:

• power- Khi được đổi thành true, không có gì xảy ra ngoài một ghi chú được thực hiện rằng công tắc đã được đặt vào trạng thái này. Khi được đổi thành false, VM được lệnh chuyển sang trạng thái tắt nguồn ngay lập tức. Để hoàn thiện, nếu giá trị không thay đổi sau khi viết, không có gì xảy ra.

• onoff- Khi thay đổi true, không có gì xảy ra nếu powerlà false, nếu không thì VM được ra lệnh để bắt đầu. Khi thay đổi false, không có gì xảy ra nếu powerđược false, nếu không, VM được chỉ huy thông báo cho các phần mềm để làm một trật tự tắt máy, mà nó sẽ làm và sau đó thông báo cho VM mà nó có thể đi vào power-off nhà nước. Một lần nữa, cho đầy đủ, một văn bản không thay đổi không làm gì cả.

Với tất cả những điều này nhận ra rằng có một tình huống khi trạng thái của máy không phản ánh trạng thái của các công tắc và đó là trong khi tắt máy. powervẫn sẽ truevà onoffsẽ tồn tại false, nhưng bộ xử lý vẫn đang chạy tắt máy và chúng ta cần thêm một tài nguyên khác để có thể biết máy đang thực sự làm gì:

• running- Giá trị chỉ đọc là truekhi VM chạy và falsekhi không, xác định bằng cách yêu cầu trình ảo hóa cho trạng thái của nó.

Kết quả cuối cùng là nếu bạn muốn VM khởi động, bạn phải đảm bảo rằng các tài nguyên powervà onoffđã được thiết lập true. (Bạn có thể cho phép các powerbước để được bỏ qua bằng cách làm cho nó tự đặt, do đó nếu thiết lập để false, nó trở nên truesau khi VM đã được verifiably khó dừng lại Cho dù đó là một điều RESTfully tinh khiết để làm. Là thức ăn gia súc để thảo luận khác.) Nếu bạn muốn nó làm một trật tự tắt máy, bạn thiết lập onoffđể falsevà quay lại sau để xem nếu máy thực sự dừng lại, thiết lập powerđể falsenếu nó không.

Giống như thế giới thực, bạn vẫn gặp vấn đề khi được hướng dẫn khởi động VM sau khi nó được onoffđổi thành falsenhưng vẫn còn runningvì nó đang ở giữa tắt máy. Làm thế nào bạn đối phó với đó là một quyết định chính sách.

Cả hai thiết kế RESTful?

Vì vậy, nếu bạn muốn suy nghĩ yên tĩnh thì hãy quên các lệnh. Máy khách không báo cho máy chủ tắt VM. Máy khách "tắt dow" (nói một cách ẩn dụ) bản sao biểu diễn tài nguyên của chúng bằng cách cập nhật trạng thái của nó và sau đó PUT đại diện lại trên máy chủ. Máy chủ chấp nhận rằng đại diện trạng thái mới và như là một tác dụng phụ của việc này, thực sự tắt VM. Các khía cạnh hiệu ứng phụ được để lại cho máy chủ.

Nó là ít

Này máy chủ, máy khách ở đây, bạn có phiền khi tắt VM không

và nhiều hơn nữa của

Này máy chủ, máy khách ở đây, tôi đã cập nhật trạng thái tài nguyên VM 42 sang trạng thái tắt máy, cập nhật bản sao của tài nguyên này và sau đó làm những gì bạn nghĩ là phù hợp

Là một tác dụng phụ của máy chủ chấp nhận trạng thái mới này, nó có thể kiểm tra những hành động mà nó phải thực hiện (chẳng hạn như tắt VM 42), nhưng điều này là trong suốt đối với máy khách. Máy khách không quan tâm đến bất kỳ hành động nào mà máy chủ phải thực hiện để trở nên phù hợp với trạng thái mới này

Vì vậy, quên đi các lệnh. Các lệnh duy nhất là các động từ trong HTTP để chuyển trạng thái. Máy khách không biết, cũng không quan tâm, máy chủ sẽ đưa VM vật lý vào trạng thái tắt như thế nào. Máy khách không phát lệnh cho máy chủ để đạt được điều này, nó chỉ nói Đây là trạng thái mới, hãy tìm ra nó .

Sức mạnh của điều này là nó tách máy khách khỏi máy chủ về mặt kiểm soát luồng. Nếu sau này máy chủ thay đổi cách thức hoạt động với VM, máy khách không quan tâm. Không có điểm cuối lệnh để cập nhật. Trong RPC nếu bạn thay đổi điểm cuối API từ shutdownđể shut-downbạn đã phá vỡ tất cả các khách hàng của bạn khi họ bây giờ không biết lệnh để gọi trên máy chủ.

REST tương tự như lập trình khai báo, trong đó thay vì liệt kê một tập các hướng dẫn để thay đổi một cái gì đó bạn thay vào đó chỉ nêu cách bạn muốn và để môi trường lập trình tìm ra nó.