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...