1.10. The Mailbox RESTful API¶

This is a proposed API for the GNU Taler Mailbox service which allows Taler wallets to securely send push and pull payment requests to other wallets without having to interact with the respective messaging service.

The API specified here follows the general conventions for all details not specified in the individual requests. The glossary defines all specific terms used in this section.

1.10.1. Terms of service API¶

These APIs allow clients to obtain the terms of service and the privacy policy of a service.

GET /terms¶

Get the terms of service of the service. The endpoint will consider the “Accept” and “Accept-Language” and “Accept-Encoding” headers when generating a response. Specifically, it will try to find a response with an acceptable mime-type, then pick the version in the most preferred language of the user, and finally apply compression if that is allowed by the client and deemed beneficial.

The endpoint will set an “Etag”, and subsequent requests of the same client should provide the tag in an “If-None-Match” header to detect if the terms of service have changed. If not, a “304 Not Modified” response will be returned. Note that the “304 Not Modified” will also be returned if the client changed the “Accept-Language” or “Accept-Encoding” header. Thus, if the client would like to download the resource in a different language or format, the “If-None-Match” header must be omitted.

If the “Etag” is missing, the client should not cache the response and instead prompt the user again at the next opportunity. This is usually only the case if the terms of service were not configured correctly.

When returning a full response (not a “304 Not Modified”), the server should also include a “Avail-Languages” header which includes a comma-separated list of the languages in which the terms of service are available in (see availability hints specification). Clients can use this to generate a language switcher for users that may not have expressed a proper language preference.

GET /privacy¶: Get the privacy policy of the service. Behaves the same way as The “/terms” endpoint, except that it returns the privacy policy instead of the terms of service.

1.10.2. Configuration information¶

GET /config¶

Return the protocol version and currency supported by this service.

Response:

200 OK:: The body is a VersionResponse.

Details:

interface VersionResponse {
  // libtool-style representation of the Merchant protocol version, see
  // https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning
  // The format is "current:revision:age".
  version: string;

  // Name of the protocol.
  name: "taler-mailbox";

  // Fee per message.
  message_fee: Amount;

  // How long will the service store a message
  // before giving up on delivery?
  delivery_period: RelativeTime;

}

1.10.3. Sending messages¶

POST /$H_MAILBOX¶

Puts a message into $H_MAILBOX. $H_MAILBOX is the SHA512 of an EdDSA public key.

Request

The body of the request must be an IdentityMessage.

Response

204 No Content: Message was stored and will be delivered.
402 Payment Required: Client needs to make a Taler payment before proceeding. See standard Taler payment procedure.
403 Forbidden: The specified order_id does not permit sending of this message. Possible reaons include the order being for a different message, unpaid or malformed. This response comes with a standard ErrorDetail response.
429 Too Many Requests:: The system is currently experiencing a too high request load and is unable to accept the message for delivery. The response format is given by MailboxRateLimitedResponse.

Details:

interface IdentityMessage {
  // Public DH key used to encrypt the body. Must be fresh
  // and only used once (ephemeral).
  ephemeral_key: EcdhePublicKey;

  // Encrypted message. Must be exactly 256-32 bytes long.
  body: string;

  // Order ID, if the client recently paid for this message.
  order_id?: string;
}

interface MailboxRateLimitedResponse {

  // Taler error code, TALER_EC_MAILBOX_DELIVERY_RATE_LIMITED.
  code: number;

  // When the client should retry.
  retry_delay: RelativeTime;

  // The human readable error message.
  hint: string;

}

1.10.4. Receiving messages¶

GET /$H_MAILBOX¶

Endpoint that returns unread messages in $H_MAILBOX. The number of messages returned by the service can be limited. If the request is simply repeated, the same messages will be returned again (or possibly more if additional messages arrived and the total number is below the service’s current internal limit). To receive additional messages, the client generally has to first explicitly DELETE already downloaded messages from the mailbox.

Request:

Query Parameters:

timeout_ms=NUMBER – Optional. If specified, the Mailbox service will wait up to NUMBER milliseconds for the arrival of new messages before sending the HTTP response. Note that if the mailbox is non-empty, the service will always return immediately with the messages in the mailbox, and not wait for additional messages to arrive.

Response

200 Ok:: Messages are returned in binary format, 256 bytes per message, starting with the ephemeral key and followed by the encrypted body. Messages are not encapsulated in JSON!
204 No Content:: The mailbox is empty.
429 Too Many Requests:: The system is currently experiencing a too high request load and is unable to accept the message for delivery. The response format is given by MailboxRateLimitedResponse.

DELETE /$ADDRESS¶

Requests the deletion of already received messages from the mailbox. Here, $ADDRESS must be the EdDSA public key of the mailbox (not the hash!).

Request

The body of the request must be a MessageDeletionRequest.

Details:

interface MessageDeletionRequest {

// Number of messages to delete. (Starting from the beginning
// of the latest GET response).
count: Integer;

// SHA-512 hash over all messages to delete.
checksum: HashCode;

// Signature by the mailbox's private key affirming
// the deletion of the messages, of purpuse
// TALER_SIGNATURE_WALLET_MAILBOX_DELETE_MESSAGES.
wallet_sig: EddsaSignature;

}

Response

204 No Content:: Deletion complete.
403 Forbidden:: The wallet_sig is invalid. This response comes with a standard ErrorDetail response.
404 Not found:: The checksum does not match the messages currently at the head of the mailbox, or count is larger than the number of messages currently in the mailbox. This response comes with a standard ErrorDetail response.

1.9. The TalDir RESTful API

1.11. Bank RESTful APIs