asynchronous POST to the message API

[monkeypants]

In the doc, (section "Message API") you state:

response is 200 OK if the message is successfully
processed by the relevant DLT channel

I don't think that's quite right.

• picky: it should be 201 (created), not 200 (OK)
• The 200 means the message was posted to the API, and it's in a queue for writing to the ledger.

Written vs. not-written is a bit nuanced in DLT. It's a slightly arbitrary decision, how many blocks on top of the last block do you consider successfully written? In other words, how deeply might a fork run before it's resolved? That question is technology specific, so should be answered by a technology specific component, not the generic interface.

Suggest an alternative that POST {message} /{message api}/ should return 201 and some sender reference (receipt), and subsequent calls to GET /{message api}/{receipt} should return a status of pending, accepted or rejected. That way, the technology specific apparatus of the channel can make a decision about the status of the message asynchronously.

[monkeypants]

@onthebreeze's comment in #14 means that we should POST a list of messages (not an individual message), and receive a list of receipts in response.

[monkeypants]

Note also: if the message TX API returns a receipt (which is a reference number, generated by the node that writes to the ledger), then there will be a difference with the message RX API.

message TX API:

• does not accept a receipt number
• generates a receipt number and returns it

message RX API

• requires a receipt number to be given to it
• does not accept messages without a receipt number
• uses the receipt number to update the status of the message (yes, we accepted it).

Because we are creating messages with status=pending, we need something that updates the status with something like PATCH {status=rejected} /message_tx_api/{receipt}. In other words, the message TX API would need to support a patch method that the message RX API doesn't need to.

The blockchain observer component (channel specific) could be responsible for patching the message to update the status (status=accepted or status=rejected), which is only possible if the status=pending.

[monkeypants]

also - message TX API definitely needs to be asynchronous, but I'm not sure that message RX API needs to be.