add tag api docs

contents/dapp_developer/index.rst

@@ -35,6 +35,7 @@ We conclude by summarizing the various URL schemes that provide simple HTTP endp
 .. include:: ../features/act.rst
 .. include:: ../features/fuse.rst
 .. include:: ../features/pin.rst
+.. include:: ../features/tag.rst
 .. include:: ../features/bzz.rst
 
 .. include:: ../messaging/pss.rst

contents/dapp_developer/upload_cli.rst

@@ -8,12 +8,24 @@ Uploading a file to your local Swarm node
 
 .. note:: Once a file is uploaded to your local Swarm node, your node will `sync` the chunks of data with other nodes on the network. Thus, the file will eventually be available on the network even when your original node goes offline.
 
+.. important:: According to your Swarm node's configuration different syncing mode will be used. If your Swarm node is configured to operate in push-sync mode only - your origin address will be leaked for the proof of custody receipts
+
 The basic command for uploading to your local node is ``swarm up FILE``. For example, let's create a file called example.md and issue the following command to upload the file example.md file to your local Swarm node.
 
 .. code-block:: none
   
   $ echo "this is an example" > example.md
   $ swarm up example.md
+    Swarm Hash: 730c96f6de2b5b3b961b3cf1ca0916efe2543a13a6da31e1083c61b08adc3602
+    Tag UID: 672245080
+    Upload status:
+    Syncing 23 chunks       12s [--------------------------------------------------------------] 0 %
+
+In order to produce machine-readable output of the ``swarm up`` command, use the ``--no-track`` flag after the ``up`` keyword as follows:
+
+.. code-block:: none
+  
+  $ swarm up --no-track example.md
   > d1f25a870a7bb7e5d526a7623338e4e9b8399e76df8b634020d11d969594f24a
 
 The hash returned is the hash of a :ref:`swarm manifest <swarm-manifest>`. This manifest is a JSON file that contains the ``example.md`` file as its only entry. Both the primary content and the manifest are uploaded by default.
@@ -326,4 +338,4 @@ Up- and downloading in the CLI: example usage
       > <new dir hash 2>
 
     We can check the manifest under <new dir hash 2> to see that the file is back there.
-
+

contents/features/bzz.rst

@@ -27,7 +27,7 @@ returns a readme.md file if the manifest at the given hash address contains such
     $ curl http://localhost:8500/bzz-raw:/c4c81dbce3835846e47a83df549e4cad399c6a81cbf83234274b87d49f5f9020/readme.md
     ## Hello Swarm!
 
-    Swarm is awesome%
+    Swarm is awesome
 
 If the manifest does not contain an file at ``readme.md`` itself, but it does contain multiple entries to which the URL could be resolved, e.g. in the example above, the manifest has entries for ``readme.md.1`` and ``readme.md.2``, the API returns an HTTP response "300 Multiple Choices", indicating that the request could not be unambiguously resolved. A list of available entries is returned via HTTP or JSON.
 
@@ -191,7 +191,7 @@ The same as the generic scheme but there is no ENS domain resolution, the domain
     $ curl http://localhost:8500/bzz-immutable:/679bde3ccb6fb911db96a0ea1586c04899c6c0cc6d3426e9ee361137b270a463/readme.md.1
     ## Hello Swarm!
 
-    Swarm is awesome%
+    Swarm is awesome
     $ curl -H "Accept:application/json" http://localhost:8500/bzz-immutable:/theswarm.eth/ | jq .
     {
         "Msg": "cannot resolve theswarm.eth: immutable address not a content hash: \"theswarm.eth\"",

contents/features/tag.rst

@@ -0,0 +1,89 @@
+
+Tags
+-----
+
+Tags are meant as a complementary component to track the state of an upload on Swarm. Tags consist mainly of counters and their sole purpose is to track and expose information necessary to display the progress of your uploads.
+Whenever you upload content, a tag is automatically created in order to allow tracking of your upload in its various stages.
+
+The tag API is supported through two different interfaces: CLI and HTTP.
+
+
+CLI
+^^^^
+
+The tag API can will displayed through the command line interface through the ``swarm up`` command.
+When uploading a file, the status will be shown by default with a simple progress bar. This uses tags under the hood through the HTTP server:
+
+.. code-block:: none
+  
+  $ echo "this is an example" > example.md
+  $ swarm up example.md
+    Swarm Hash: 730c96f6de2b5b3b961b3cf1ca0916efe2543a13a6da31e1083c61b08adc3602
+    Tag UID: 672245080
+    Upload status:
+    Syncing 23 chunks       0s [==============================================================] 100 %
+    Done! Your file is now retrievable from other Swarm nodes
+
+In order to produce machine-readable output of the ``swarm up`` command, use the ``--no-track`` flag after the ``up`` keyword as follows:
+
+.. code-block:: none
+  
+  $ echo "this is an example" > example.md
+  $ swarm up --no-track example.md
+    730c96f6de2b5b3b961b3cf1ca0916efe2543a13a6da31e1083c61b08adc3602
+
+.. important:: The Swarm hash that was returned from the ``swarm up`` command does not infer your Swarm node has finished syncing the content to the network. You will have to wait until your content is synced until it is accessible from other Swarm nodes
+
+
+HTTP
+^^^^^^
+
+The tag API can be accessed by HTTP using the ``GET`` verb on the ``bzz-tag:/`` locator.
+
+``bzz-tag`` can track a tag by two parameters - either the Swarm hash or the tag UID of the upload.
+
+You can find the tag UID of the upload in the data returned alongside the progress bar while using ``swarm up``. Tag retrieval by UID is meant for a future implementation that would allow tracking an upload that has not returned a Swarm hash yet; i.e. it is still being split and stored on the local node.
+
+When uploading to Swarm via HTTP ``POST``, the tag UID will be returned as a header named ``x-swarm-tag``. This allows for programmatic access to tags for Dapp developers that would like to display upload progress to their users.
+
+The tag associated with a Swarm hash can be retrieved with the hash inlined after ``bzz-tag:/`` while the tag associated with the tag UID can be retrieved using the UID as a query variable.
+
+Using the Swarm Hash:
+
+
+.. code-block:: none
+
+   $ curl localhost:8500/bzz-tag:/730c96f6de2b5b3b961b3cf1ca0916efe2543a13a6da31e1083c61b08adc3602
+   {
+    "Uid": 12210768,
+    "Name": "Some upload",
+    "Address": "730c96f6de2b5b3b961b3cf1ca0916efe2543a13a6da31e1083c61b08adc3602",
+    "Total": 2,
+    "Split": 2,
+    "Seen": 2,
+    "Stored": 2,
+    "Sent": 0,
+    "Synced": 0,
+    "StartedAt": "2019-09-30T12:20:11.176316707+05:30"
+   }
+
+
+Using the tag UID:
+
+.. code-block:: none
+
+   $ curl localhost:8500/bzz-tag:/&Id=12210768
+   {
+    "Uid": 12210768,
+    "Name": "Some upload",
+    "Address": "730c96f6de2b5b3b961b3cf1ca0916efe2543a13a6da31e1083c61b08adc3602",
+    "Total": 2,
+    "Split": 2,
+    "Seen": 2,
+    "Stored": 2,
+    "Sent": 0,
+    "Synced": 0,
+    "StartedAt": "2019-09-30T12:20:11.176316707+05:30"
+   }
+
+