diff --git a/docs/source/interface.rst b/docs/source/interface.rst index 2c004f26b3debbc8232df50a2095abc0fdbc9190..678d5c45973b040cf45e34f94f415674887b9574 100644 --- a/docs/source/interface.rst +++ b/docs/source/interface.rst @@ -42,15 +42,20 @@ If the voucher is not known then the response is **NOT FOUND**. For any voucher which has previously been submitted, the response is **OK** with an ``application/json`` content-type response body like:: - { "number": <string> + { "version": 1 + , "number": <string> , "expected-tokens": <integer> , "created": <iso8601 timestamp> , "state": <state object> - , "version": 1 } +The ``version`` property indicates the semantic version of the data being returned. +When properties are removed or the meaning of a property is changed, +the value of the ``version`` property will be incremented. +The addition of new properties is **not** accompanied by a bumped version number. + The ``number`` property merely indicates the voucher which was requested. -The ``expected-tokens`` property indicates the total number of ZKAPs the client for which the client intends to redeem the voucher. +The ``expected-tokens`` property indicates the total number of ZKAPs for which the client intends to redeem the voucher. Vouchers created using old versions of ZKAPAuthorizer will have a best-guess value here because the real value was not recorded. The ``created`` property indicates when the voucher was first added to the node. The ``state`` property is an object that gives more details about the current state of the voucher. @@ -69,6 +74,7 @@ The integer *counter* value indicates how many successful sub-redemptions have c , "counter": <integer> } +The *started* timestamp gives the time when the most recent redemption attempt began. The integer *counter* value has the same meaning as it does for the *pending* state. :: @@ -78,18 +84,25 @@ The integer *counter* value has the same meaning as it does for the *pending* st , "token-count": <number> } +The *finished* timestamp gives the time when redemption completed successfully. +The integer *token-count* gives the number tokens for which the voucher was redeemed. + :: { "name": "double-spend" , "finished": <iso8601 timestamp> } +The *finished* timestamp gives the time when the double-spend error was encountered. + :: { "name": "unpaid" , "finished": <iso8601 timestamp> } +The *finished* timestamp gives the time when the unpaid error was encountered. + :: { "name": "error" @@ -97,10 +110,8 @@ The integer *counter* value has the same meaning as it does for the *pending* st , "details": <text> } -The ``version`` property indicates the semantic version of the data being returned. -When properties are removed or the meaning of a property is changed, -the value of the ``version`` property will be incremented. -The addition of new properties is **not** accompanied by a bumped version number. +The *finished* timestamp gives the time when this other error condition was encountered. +The *details* string may give additional details about what the error was. ``GET /storage-plugins/privatestorageio-zkapauthz-v1/voucher`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~