[Question] Why doesn't OrdersController follow common REST guidelines?

[jsangco]

• POST api/v1/orders/ship to ship an order
• POST api/v1/orders/cancel to cancel an order

The best practices I'm aware of are that verbs be avoided in RESTful APIs, so is there a reason that these verbs were chosen?

[mvelosop]

Hi @jsangco

Well let's call in someone that's been in the project from the beginning, perhaps @eiximenis or @unaizorrilla.

In the meantime, we might just discuss about this, as I really find this topic interesting.

What I've read so far about API best practices do state, as you mentioned, that nouns should be used, be the samples I've seen are also about trivial examples.

So I don't see how to map a resource oriented best practice to a command oriented API.

Thoughts?

[MrDywar]

Hi.

The REST API has a thing like "controller".

1. A REST API is composed of 4 distinct resource archetypes: document, collection, store and controller.
2. A controller resource models a procedural concept. Controller resources are like executable functions, with inputs and return values. A REST API relies on controller resources to perform application specific actions that cannot be logically mapped to one of the standard methods (create, retrieve, update and delete).

*Controllers always should be called with POST.

And the examples above follow these rules.

[mvelosop]

Hi @MrDywar,

Thanks a lot for such a concise explanation 👍

Cheers 😊

Closing this issue now!