[Taler] a more RESTful merchant backend API

[Florian Dold]

Hi *,

What follows isn't something I want to implement "right now", but some
ramblings about how to make the merchant API better, at least in my
opinion.  Comments welcome!

One of the six architectural constraints for RESTful APIs is "uniform
interface".  I think we're currently not really doing this justice,
leading to an API that is harder to understand than it could be.

By now, the main resources we have available have crystallized pretty well:

- Merchant instances
-- Orders
---- wire transfers that involve the order
-- Wire transfers to the merchant's bank account
   (currently not yet tracked by the merchant backend)
--- orders involved in a wire transfer
-- A tipping reserve
-- Tips

However, the current API hides this very well!  The available end points
aren't really referring to resources and their children, but instead are
like "remote procedure calls" with parameters.

The worst part of this is the /track/transfer & /track/transaction API.
I can never remember them.  Again, it is IMHO easy to make this better
by actually structuring it around resources!

I am not even talking about changing the API drastically, this is mostly
about renaming and consistency!

An actual RESTful API would look somewhat like this:

POST /orders
(Create a new order, same as the existing POST /order.  But plural,
since orders are a collection of things.)

GET /orders/${order_id}
(Look up an existing order.  Essentially, this is the same as
/check-payment, but with an easy-to-remember name that follows from the
resource that was previously created.  We refer to the resource by it's
"primary key", i.e., the order ID.)

GET /orders
(this is basically the history API, with same query params.)

POST /public/orders/${order_id}/claim
(Claim an existing order as a wallet/customer.  The sub-resource here
identifies an action that is part of the parent object.)

GET /public/orders/${order_id}
(look up *public* information about the order, i.e. retrieve the
contract terms for it as well as refund status and payment status.
"/public" is basically the root of the "publicly accessible view" on the
merchant backend.)

POST /public/orders/${order_id}/coins
(same as /pay.)

POST /orders/${order_id}/refunds
(same as /refund, authorize a refund)

GET /orders/${order_id}/refunds
(Look up refunds for an order, including the internal justification.
This might be rolled into "GET /orders/${order_id}" though.)

GET /orders/${order_id}/wire-transfers
(This is /track/transaction.  Basically, we look up all wire transfers
that the exchange made for this order (or when future wire transfers
will happen for this order).)

Now, I am not sure why we need "/track/transfer" API in the current form
for the merchant backend / back-office.  Don't we want to track in our
merchant database which wire transfers we've actually *received*?  If
that's the case, the following API would be more appropriate:

POST /transfers
(Notify the merchant backend about a transaction we received into the
merchant's bank account.  This will use the exchanges /track/transfer
API to check if the bank statement is consistent with what the exchange
says.)

GET /transfers
(List wire transfers we received.)

GET /tipping-reserve
(Get information about the tipping reserve used by this instance, if one
is defined.)

POST /tips
(Authorize a tip)

GET /tips
("History" of tips.  Currently this isn't even implemented, AFAIK.)

GET /public/tips/${tip_id}
(Get information about a tip, like the amount and how much of it has
been claimed.)

POST /public/tips/${tip_id}/pick-up
(Pick up the tip, by making the merchant sign the planchets.)

The /instances API is already "RESTful".

A note on PUT vs POST:  PUT is supposed to be (1.) idempotent and (2.)
replace or create the resource denoted by the request URI.  Neither of
these apply to any of these APIs, that's why we're not using PUT.

- Florian