Swarm API improvements

swarm-api-improvements.md

Uploading files

Files can be uploaded in a single HTTP request, where the body is either a single file to store, a tar stream (application/x-tar) or a multipart form (multipart/form-data).

• single file upload

$ curl -H "Content-Type: text/plain" --data-binary "some-data" http://localhost:8500/bzz:/
69094f7a9a04d680708596d1c0b67b0852d72d91bbaf934206c0904137c5a3c7

$ curl http://localhost:8500/bzz:/69094f7a9a04d680708596d1c0b67b0852d72d91bbaf934206c0904137c5a3c7/
some-data

• tar stream

$ ( mkdir dir1 dir2; echo "some-data" | tee dir1/file.txt | tee dir2/file.txt; )

$ tar c dir1/file.txt dir2/file.txt | curl -H "Content-Type: application/x-tar" --data-binary @- http://localhost:8500/bzz:/
1e0e21894d731271e50ea2cecf60801fdc8d0b23ae33b9e808e5789346e3355e

$ curl http://localhost:8500/bzz:/1e0e21894d731271e50ea2cecf60801fdc8d0b23ae33b9e808e5789346e3355e/dir1/file.txt
some-data

$ curl http://localhost:8500/bzz:/1e0e21894d731271e50ea2cecf60801fdc8d0b23ae33b9e808e5789346e3355e/dir2/file.txt
some-data

• multipart form

$ curl -F 'dir1/file.txt=some-data;type=text/plain' -F 'dir2/file.txt=some-data;type=text/plain' http://localhost:8500/bzz:/                                                                                                         
9557bc9bb38d60368f5f07aae289337fcc23b4a03b12bb40a0e3e0689f76c177

$ curl http://localhost:8500/bzz:/9557bc9bb38d60368f5f07aae289337fcc23b4a03b12bb40a0e3e0689f76c177/dir1/file.txt                                                                                                                     
some-data

$ curl http://localhost:8500/bzz:/9557bc9bb38d60368f5f07aae289337fcc23b4a03b12bb40a0e3e0689f76c177/dir2/file.txt
some-data

Files can also be added to an existing manifest:

$ curl -F 'dir3/file.txt=some-other-data;type=text/plain' http://localhost:8500/bzz:/9557bc9bb38d60368f5f07aae289337fcc23b4a03b12bb40a0e3e0689f76c177                                                                                
ccef599d1a13bed9989e424011aed2c023fce25917864cd7de38a761567410b8

$ curl http://localhost:8500/bzz:/ccef599d1a13bed9989e424011aed2c023fce25917864cd7de38a761567410b8/dir1/file.txt
some-data

$ curl http://localhost:8500/bzz:/ccef599d1a13bed9989e424011aed2c023fce25917864cd7de38a761567410b8/dir3/file.txt
some-other-data

Files can also be uploaded using a simple HTML form:

<form method="POST" action="/bzz:/" enctype="multipart/form-data">
  <input type="file" name="dir1/file.txt">
  <input type="file" name="dir2/file.txt">
  <input type="submit" value="upload">
</form>

Downloading files

GET requests work the same as before with the added ability to download multiple files by setting Accept: application/x-tar:

$ curl -s -H "Accept: application/x-tar" http://localhost:8500/bzz:/ccef599d1a13bed9989e424011aed2c023fce25917864cd7de38a761567410b8/ | tar t
dir1/file.txt
dir2/file.txt
dir3/file.txt

Listing files

Setting list=true in the query of a GET request returns a list of files contained under the path, grouped into common prefixes which represent directories:

$ curl -s http://localhost:8500/bzz:/ccef599d1a13bed9989e424011aed2c023fce25917864cd7de38a761567410b8/?list=true | jq .                                                                                                              
{
  "common_prefixes": [
    "dir1/",
    "dir2/",
    "dir3/"
  ]
}

$ curl -s http://localhost:8500/bzz:/ccef599d1a13bed9989e424011aed2c023fce25917864cd7de38a761567410b8/dir1/?list=true | jq .
{
  "entries": [
    {
      "path": "dir1/file.txt",
      "contentType": "text/plain",
      "size": 9,
      "mod_time": "2017-03-12T15:19:55.112597383Z",
      "hash": "94f78a45c7897957809544aa6d68aa7ad35df695713895953b885aca274bd955"
    }
  ]
}

Setting Accept: text/html returns the list as a browsable HTML document:

---

👍 Nice work. Is the result of requesting a path via bzz which was uploaded as a tar stream, receiving the manifest listing the directory and file structure, or receiving the binary tar file?

@dob apologies I only just saw your comment.

When you upload a tar stream the files are extracted on the server and stored individually, so when you get the manifest it will list the directory and file structure.

If you want a tar file representing the original upload, you can use Accept: application/x-tar in a GET request, and that works for any manifest (not just those originally uploaded as a tar stream).

👍