In this article the author claims thatSometimes, it is required to expose an operation in the API that inherently is non RESTful. and that If an API has too many actions, then thats an indication that either it was designed with an RPC viewpoint rather than using RESTful principles, or that the API in question is naturally a better fit for an RPC type model.This reflects what I have read and heard elsewhere as well.However I find this quite confusing and I would like to get a better understanding of the matter.Example I: Shutting down a VM through a REST interfaceThere are, I think, two fundamentally different ways to model a shutdown of a VM. Each way might have a few variations, but let's concentrate on the most fundamental differences for now.1. Patch the resource's state propertyPATCH /api/virtualmachines/42Content-Type:application/json  { state: shutting down }(Alternatively, PUT on the sub-resource /api/virtualmachines/42/state.)The VM will be shutting down in the background and at some later point in time depending of wether shutting down will succeed or not the state might be internally updated with power off.2. PUT or POST on the resource's actions propertyPUT /api/virtualmachines/42/actionsContent-Type:application/json  { type: shutdown }The result is exactly the same as in the first example. The state will be updated to shutting down immediately and maybe eventually to power off.Are both designs RESTful?Which design is better?Example II: CQRSWhat if we have a CQRS domain with many such actions (aka commands) that might potentially lead to updates of multiple aggregates or cannot be mapped to CRUD operations on concrete resources and sub-resources?Should we try to model as many commands as concrete creates or updates on concrete resources, where ever possible (following the first approach from example I) and use action endpoints for the rest?Or should we map all the commands to action endpoints (as in the second approach of example I)?Where should we draw the line? When does the design become less RESTful?Is a CQRS model a better fit for an RPC like API?According to the quoted text above it is, as I understand it.As you can see from my many questions, I am a little bit confused about this topic. Can you help me to get a better understanding of it?
How does a REST API fit for a command/action based domain?
rest;domain driven design;api design;cqrs
In the first case (shut-down of VMs), I'd consider none of the OP alternatives RESTful. Granted, if you use the Richardson maturity model as a yardstick, they are both leve 2 APIs because they use resources and verbs.Neither of them, though, use hypermedia controls, and in my opinion, that's the only type of REST that differentiates RESTful API design from RPC. In other words, stick with level 1 and 2, and you're going to have an RPC-style API in most cases.In order to model two different ways of shutting down a VM, I'd expose the VM itself as a resource that (among other things) contains links:{    links: [{        rel: shut-down,        href: /vms/1234/fdaIX    }, {        rel: power-off,        href: /vms/1234/CHTY91    }],    name: Ploeh,    started: 2016-08-21T12:34:23Z}If a client wishes to shut down the Ploeh VM, it ought to follow the link with the shut-down relationship type. (Normally, as outlined in the RESTful Web Services Cookbook, you'd use an IRI or more elaborate identification scheme for relationship types, but I chose to keep the example as simple as possible.)In this case, there's little other information to provide with the action, so the client should simple make an empty POST against the URL in the href:POST /vms/1234/fdaIX HTTP/1.1(Since this request has no body, it'd be tempting to model this as a GET request, but GET requests should have no observable side-effects, so POST is more correct.)Likewise, if a client wants to power off the VM, it'll follow the power-off link instead.In other words, the relationship types of the links provide affordances that indicate intent. Each relationship type has a specific semantic significance. This is the reason we sometimes talk about the semantic web.In order to keep the example as clear as possible, I intentionally obscured the URLs in each link. When the hosting server receives the incoming request, it'd know that fdaIX means shut down, and CHTY91 means power off.Normally, I'd just encode the action in the URL itself, so that the URLs would be /vms/1234/shut-down and /vms/1234/power-off, but when teaching, that blurs the distinction between relationship types (semantics) and URLs (implementation details).Depending on which clients you have, you may consider making RESTful URLs non-hackable.CQRSWhen it comes to CQRS, one of the few things that Greg Young and Udi Dahan agrees about is that CQRS isn't a top-level architecture. Thus, I'd be cautious about making a RESTful API too CQRS-like, because that'd mean that clients become part of your architecture.Often, the driving force behind a real (level 3) RESTful API is that you want to be able to evolve your API without breaking clients, and without having control of clients. If that's your motivation, then CQRS wouldn't be my first choice.