taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

delete-ADDRESS.rst (2280B)

      1 .. http:delete:: /$ADDRESS
      2 
      3   Requests the deletion of already received messages from the
      4   mailbox. Here, ``$ADDRESS`` must be the EdDSA public key
      5   of the mailbox (not the hash!).
      6   The ``ETag`` header returned by a GET request for messages
      7   returns the ID for the first message received.
      8   This allows the caller to select a range of messages starting
      9   from the first message received in the last GET call
     10   to delete.
     11 
     12   **Request**
     13 
     14   The header ``Match-If`` must be set to the ID of the first message
     15   to delete.
     16   The ``ETag`` value is retrieved when receiving messages via a GET
     17   request.
     18   For example, a ``Match-If`` header value of 2 and a count field of
     19   5 will delete messages from ID 2 to N such that up to 5 messages are
     20   deleted.
     21   The ``Taler-Mailbox-Delete-Signature`` header must be set with a
     22   Base32-Crockfor encoded signature over four 32 bit values in
     23   network byte order: ``NBO(16)||NBO(TALER_SIGNATURE_MAILBOX_DELETE_MESSAGES)||NBO(Etag)||NBO(count)``
     24   where ``TALER_SIGNATURE_MAILBOX_DELETE_MESSAGES`` is a signature purpose value registered in
     25   GANA.
     26 
     27   :query count=NUMBER: *Optional.*  If specified,
     28     the Mailbox service will delete up to ``NUMBER``
     29     of new messages starting from the ID provided
     30     in ``Match-If``.
     31     If the parameter is not provided, only a single
     32     message will be deleted.
     33 
     34 
     35   **Details:**
     36 
     37   .. _MessageDeletionRequest:
     38   .. ts:def:: MessageDeletionRequest
     39 
     40     interface MessageDeletionRequest {
     41 
     42       // Number of messages to delete. (Starting from the beginning
     43       // of the latest GET response).
     44       count: Integer;
     45 
     46       // Signature by the mailbox's private key affirming
     47       // the deletion of the messages, of purpuse
     48       // ``TALER_SIGNATURE_MAILBOX_DELETE_MESSAGES``.
     49       signature: string;
     50 
     51     }
     52 
     53   **Response**
     54 
     55   :http:statuscode:`204 No Content`:
     56      Deletion complete.
     57   :http:statuscode:`403 Forbidden`:
     58      The ``signature`` is invalid.
     59      This response comes with a standard `ErrorDetail` response.
     60   :http:statuscode:`404 Not found`:
     61      The checksum does not match the messages currently at the
     62      head of the mailbox, or ``count`` is larger
     63      than the number of messages currently in the mailbox.
     64      This response comes with a standard `ErrorDetail` response.