Maybe this is a real debate in some circles, but I cannot fathom mapping HTTP verbs directly to SQL statements.
> POST /orders/42/shipment
Fixed?
GET /order/42/payment/new (returns "3", for example)
PUT /order/42/payment/3 (supplying content for payment info and amount)
Re-issuing the "PUT" (in case confirmation was lost? user double clicked "submit"?) would simply resend the same value, thus, an "idempotent" action.
Viewing this particular payment is simply:
GET /order/42/payment/3
Without the "3", who knows which payment you would get? (unless you got back the list of all payments on the order so far)
I'm not sure if this an argument for or against REST, but I'd sure hate to see a SOAP example typed into a "comment box" in a discussion forum :-)
If the payment doesn't cover the bill, you could have the PUT respond with a link to /order/42/payment/remaining/1, then (if needed) continue with /remaining/2, and so on.
That would avoid the danger of a gap between your id GET and the payment PUT.
POST /payment
order=42
Or: POST(or PUT) /order/42
status=shipped"customers" are used to thinking in terms of actions. You hit this little button here for payment, you hit this other little button here for shipment. And for developers, these are like methods containing business logic belonging to an object.
So where's the problem?
GET /orders/42/pay is a verb on a verb. Maybe not complex, but definitely confusing.
That's the most natural mapping, the verb PAY on the object of order 42. Maybe HTTP needs arbitrary verbs instead of a limited predefined set? We'd have to get firewalls and proxies and such out of the habit of processing a request depending on its verb.
To me it seems logical to embrace the ideas of the tool you are using. If you are not utilizing the power of HTTP, why not just use a pure RPC protocol?
I think that we eventually have to open up for more protocols if the web continues to develop into a generic dev platform. In a sense we are already heading in that direction with WebSockets. But since HTTP has been and continues to be such a success, I think that we can atleast try to promote it.
If you use hypertext in the resources to specify the places the client can go, the complexity is severely reduced. However, properly enabling discovery is where most "Rest" APIs fail.
POST was always about actions, not just resources.
> POST /orders/42/ship
But "pay" and "ship" are actions, not objects, so it doesn't make a lot of sense for them to be represented as URLs.