RESTful API Design and CQRS

Question

I was thinking of how to make a RESTFul API more intention revealing. A common patter I see around various blogs on this is that conventional REST API results in

Ban a Player -> POST /players.

But I were to change to a more intention revealing interface , I could use

Ban a Player -> POST /players/{ playerid }/banPlayer

The second one I feel is more intention revealing.

The common objection I get from the team is that the second one does not comply with start REST style.

Also currently I cannot move away from a RESTful API.

I would like to hear your thoughts on this.

Answer 1

With Restful API design there are two schools of thought around how to apply actions to a resource.

1. You describe the action to be taken against the resource in the Uri:

   Request Uri:
   POST /players/{id}/ban

   Note: Just use ban - we already know the resource is a player, its in the base Uri.

2. You can have the action in the body of the request:

   Request Uri:
   POST /players/{id}

   Request Body:
   { 'action': 'ban' }

You can pick either way - whichever you prefer, there is lots of discussion on both but ultimately both are correct.

Note:

My assumption here that banning a player is more than just updating a part of it, but rather a system action (or state transition) relating to the player. Otherwise if it was just an update to the player resource you should handle with a PATCH or PUT as appropriate.

Some discussions for reference:

• http://restful-api-design.readthedocs.io/en/latest/methods.html
• https://github.com/interagent/http-api-design/issues/58
• https://nordicapis.com/designing-a-true-rest-state-machine/
• https://softwareengineering.stackexchange.com/questions/141410/restful-state-changing-actions

With plenty more if you do some Googling...

Answer 2

Long story short: it shouldn't be mandatory to be intention revealing but if you want to add some DDD on how this API looks like then it is nothing that prevents you from doing that

According to HATEOAS constraint of a RESTful web API (this constraint is an essential part of the "uniform interface" feature of REST, as defined in Roy Fielding's doctoral dissertation), the software clients of your API should not care about the URLs. Every possible&permitted action should be included in the response, with the corresponding link relation and URI. In this way you have to hardcode only the link relations.

This constraint does not however prevent you from making the API more intention revealing for the Human clients that try to understand the overall architecture. I recommend you to choose this path, as Human users are at least as important as the software that they write.

Roy Fielding wrote about this on his blog post.