Modeling Actions in REST APIs
Ron Norman explores the strategy of modeling actions in REST APIs, emphasizing the importance of viewing actions as resources to maintain RESTful architecture. He uses practical examples, like creating orders and controlling a media player, to demonstrate how traditional actions (e.g., play, pause, launch) can be modeled as resource collections (e.g., /rocket-launches/) rather than RPC-style endpoints. This approach not only adheres to REST principles but also future-proofs API design by facilitating scalability and the addition of related functionalities
The beauty about the REST architectural style is the focus on resources and more specifically, collections. Why you might ask? One answer is the the built-in future proofing and the forcing of thinking things through upfront. What does that mean? Well, here's a simplified example.
Suppose we have a user story to process a purchase order. Normally, outside of the constraints of REST, we can simply implement an RPC style endpoint and add a /createOrder/ endpoint and be done with it. However, with REST, you would have to think of an "order" as a resource and therefore, implement an "orders" collection like this: /orders/ with a POST to create a new order.
Issuing a GET against this /orders/ collection initially will not be implemented as it wasn't required by business, but the scaffolding and the thinking process is there now. You can bet that down the line, the business will ask you to get a list of orders as a new user story, which then you would implement with GET action on the /orders/ collection. But you've already thought of that, thanks to REST resource-oriented thinking.
As you can see from the above simplified example, following REST is in a way forcing us to think through and future-proof our design. It helps us think of the resource type to expose and the list and individual item view and actions. How granular the resource should be? Etc...
Now you might ask, hey Ron, some specific actions like control-style actions don't fit well with the resource/collections model and therefore we must break away from our RESTful-ness and resort to RPC-style endpoints.
What are control-style actions? Think of a music of video player for instance. To play a video or a song, you would need a Play, Stop, Pause actions. Or say a rocket launch, you would need a Launch action. Another easier example, is a bank account actions of Withdraw, Deposit, Refund, Transfer etc...
At first glance, the above control actions seem like they do not nicely fit the REST resources/collections model and I have seen many teams implementing them as verbs at the end of an endpoint such as /rocket/launch or /account/debit or /video/play. These become REST-ish endpoints. Well, not so fast.
How do we implement those control-style actions in REST and still ahere to a RESTful and not REST-ish design? We don't want to just adhere, we want to get the benefits too. The problem is not in REST, that it cannot handle control-style actions, the problem is in abandoning REST quickly and not allowing it to provide us the benefits I mentioned above of forcing us to future-proof our endpoint design and thinking through the resource design from the get-go.
If we adhere to the REST principle that everything is a resource and REST helps us design the list view as well as the individual item view, then it becomes easy to see how to implement a control-style action.
In the example of the rocket launch, instead of thinking about the launch as a single action, let's flip it to a noun and think of many launches instead. Specifically, name the endpoint /rocket-launches/ instead of the RPC-style /rocket/launch. Then when you perform a POST on /rocket-launches/ endpoint, you're creating a new launch!
Now in the future, if business asks to see a history of the launches or what-have-you, because of REST, you've already designed the framework for that. You don't have to go and add another action like /rocket/showLaunches.
So by simply adhering to the everything-is-a-resource / collection of REST, we were able to reap the benefits of the REST architecture. I'll leave designing the other examples to model their actions in REST as an exercise for the reader.
