Skip to content

files.md

Latest commit

 

History

History
97 lines (73 loc) · 3.53 KB

files.md

File metadata and controls

97 lines (73 loc) · 3.53 KB
Raw

Files

Uploading files

Being able to upload a file to RSpace automatically can save you a lot of time and effort compared to manually uploading files using the web application. You can perform tasks such as:

  • Bulk upload of files
  • Scheduled upload of files, e.g. files generated by an instrument, sequence files, image files etc

The simplest way to upload a file is as follows:

curl -v -X POST -H "accept: application/json" -H "apiKey: $API_KEY" \
-H "content-type: multipart/form-data" -F "file=@<MY_FILE.txt>" \
"$RSPACE_URL/api/v1/files"

This will upload a file '<MY_FILE.txt>' to a default folder called 'Api Inbox' in the relevant section of the Gallery. This folder will be automatically created for you if it doesn't yet exist. JSON will be returned:

{
  "id" : 728,
  "globalId" : "GL728",
  "name" : "<MY_FILE.txt>",
  "caption" : "",
  "contentType" : "text/plain",
  "created" : "2017-07-23T09:54:16.007Z",
  "size" : 2812,
  "version" : 1,
  "_links" : [ {
     "link" : "$RSPACE_URL/api/v1/files/728",
     "rel" : "self"
   }, {
     "link" : "$RSPACE_URL/api/v1/files/728/file",
     "rel" : "enclosure"
  } ]
}

The _links property contains pre-generated links to resources created or referenced in API calls. In this case, the 'self' link will return the file metadata, and the 'enclosure' link will download the file contents. These will be described later.

You can also upload a file with an optional caption, and also specify a folder to put the file in.

curl -v -X POST -H "accept: application/json" -H "apiKey: $API_KEY" \
-H "content-type: multipart/form-data" -F "file=@<MY_FILE.txt>" \
-F "folderId=<FOLDER_ID>" -F "caption=some metadata about this file" \
"$RSPACE_URL/api/v1/files"

The caption will appear in the 'Info' section of each Gallery item, and just like a manually edited caption, will be searchable. This is a good way to add some descriptive metadata to your file so that you can locate it easily.

Browsing folders via the API is not yet supported. However it's very easy to get a folder ID from RSpace by clicking on the 'info' icon beside a Gallery folder.

Note: There are some restrictions on which folders you can upload to. For example, if uploading image files, a folder ID must be either the Gallery Images folder, or a subfolder of the images folder. You can't upload a file directly into a workspace folder or notebook.

If you're uploading many files of mixed type, then it's probably safer not to specify a single folder, but to let them be placed in the relevant API Inbox folder where you can organise them later.

Uploading files from a folder

The script batchUpload.sh will upload files sequentially from a list on the command line, e.g.

# upload a single file
./batchUpload.sh myFile.txt
# upload all png files in folder
./batchUpload.sh `ls *.png`

Replacing files

You can replace the file contents of a file by uploading a new version, using the ID obtained from an initial upload.

curl -v -X POST -H "accept: application/json" -H "apiKey: $API_KEY" \
-H "content-type: multipart/form-data" -F "file=@<MY_FILE.txt>" \
"$RSPACE_URL/api/v1/files/<FILE_ID>/file"

This will also return a JSON response of the uploaded File, with updated version property. The id will remain the same.

Downloading files

You can download files from RSpace to your device using the following syntax:

curl -v -H "accept:application/octet-stream" -H "apiKey:$API_KEY" "$RSPACE_URL/api/v1/files/<FILE_ID>/file"