From 0c2a406e1b679a26516ebee638cc75b2f2669498 Mon Sep 17 00:00:00 2001
From: Jean-Paul Calderone <exarkun@twistedmatrix.com>
Date: Fri, 4 Sep 2020 14:12:20 -0400
Subject: [PATCH] Add some interface docs for the new interface
---
docs/source/interface.rst | 31 +++++++++++++++++++++++++++++++
1 file changed, 31 insertions(+)
diff --git a/docs/source/interface.rst b/docs/source/interface.rst
index ad6c2f1..5911d12 100644
--- a/docs/source/interface.rst
+++ b/docs/source/interface.rst
@@ -180,3 +180,34 @@ The request body must be ``application/json`` encoded and contain an object like
The response is **OK** with ``application/json`` content-type response body like::
{ }
+
+``POST /storage-plugins/privatestorageio-zkapauthz-v1/calculate-price``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This endpoint allows an agent to calculate the number of ZKAPs it will cost to store a collection of files of specified sizes.
+This is intended as the basis for tools which aid in user understanding of the cost of their actions.
+
+The request body must be ``application/json`` encoded and contain an object like::
+
+ { "version": 1
+ , "sizes: [ <integer>, ... ]
+ }
+
+The ``version`` property must currently be **1**.
+The ``sizes`` property is a list of integers giving file sizes in bytes.
+
+The response is **OK** with ``application/json`` content-type response body like::
+
+ { "price": <integer>, "period": <integer> }
+
+The ``price`` property gives the number of ZKAPs which would have to be spent to store files of the given sizes.
+The ``period`` property gives the number of seconds those files would be stored by spending that number of ZKAPs.
+
+The price obtained this way is valid in two scenarios.
+First,
+the case where none of the files have been uploaded yet.
+In this case uploading the files and storing them for **period** seconds will cost **price** ZKAPs.
+Second,
+the case where the files have already been uploaded but their leases need to be renewed.
+In this case, renewing the leases so they last until **period** seconds after the current time will cost **price** ZKAPs.
+Note that in this case any lease time currently remaining on any files has no bearing on the calculated price.
--
GitLab