rDWS Storage Endpoints

9 min

Base URL for these endpoints: https://ws.bsn.cloud/rest/v1/

_________________________________________________________________________

GET /files/{:path}/

Lists the directories and/or files in a path

Segment

path string: The path to the directories or files

Query String Parameter

raw optional: Returns the raw contents of a directory

contents optional: If a file is specified, this will return the contents of that file

Request Example

GET /rest/v1/files/sd/autorun.brs/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json

Response Body

type string: Either a directory or file

path string: The path, for example, "sd"

stat object: Directory stats from the "fs" module

files object[ ]:

name string: Name of the file or directory

type string: Either "file" or "dir"

path string: The relative path of the file or directory

stat object: File stats from the “fs” module

mime string: mime type (available only for type "file")

storageInfo object: If the path in the URL is a storage device, this returns information about the storage device. For more information, see storageinfo.

fileSystemType string: The type of filesystem (for example, "fat32")

stats object:

blockSize int: The size of a native block

bytesFree int: The amount of free space

filesFree int: The number of used inodes

filesUsed int: The number of free inodes

isReadOnly bool: A flag indicating whether the filesystem is read only

sizeBytes int: The amount of total space

mountedOn string: The location where the file system is mounted (for example, "/storage/sd")

contents object[ ]:

name string: The name of the file or directory

type string: Either "file" or "dir"

path string: The absolute path of the file or directory

stat object: The statistics from the "fs" module

mime string: mime type (available only for type "file")

children object[ ]: This is available only for directory types and will have the same format as "contents

Response Body if Returning Contents

name string: The name of the file

mimeType string: Mime type of the file

contents string: The contents of the file

Response Examples

{
    "route": "/v1/files/sd/autorun.brs",
    "method": "GET",
    "data": {
        "result": {
            "name": "sd/autorun.brs",
            "type": "file",
            "path": "sd/autorun.brs",
            "mime": "application/octet-stream",
            "stat": {
                "dev": 45921,
                "mode": 33277,
                "nlink": 1,
                "uid": 0,
                "gid": 1003,
                "rdev": 0,
                "blksize": 32768,
                "ino": 40,
                "size": 1144340,
                "blocks": 2240,
                "atimeMs": 1699401600000,
                "mtimeMs": 1699423824000,
                "ctimeMs": 1699423824440,
                "birthtimeMs": 0,
                "atime": "2023-11-08T00:00:00.000Z",
                "mtime": "2023-11-08T06:10:24.000Z",
                "ctime": "2023-11-08T06:10:24.440Z",
                "birthtime": "1970-01-01T00:00:00.000Z"
            },
            "fileSize": 1144340,
            "streamable": true
        }
    }
}

If you passed in a contents query paramter in your request, you should expect a response like the one below. Note that once you have the data string, you will have to decode it (for example, with the atob method in JavaScript).

{
    "route": "/v1/files/sd/autorun.brs",
    "method": "GET",
    "data": {
        "result": {
            "mimeType": null,
            "name": "autorun.brs",
            "contents": "TGlicmFyeSAiYXV0b3B....<very-large-data-string>..."
        }
    }
}

PUT /files/{:path}

Uploads a new file or folder to the player storage

If you are uploading zip and media files, you should use BOS version 8.5.44 or 9.0.101 or later.

Segment

path string: The path is the folder in which you want to upload the file (for example: "/sd").

Request Body

files object[]:

fileName string: The name of the file

fileContents string: The content of the file. It can be provided as plain text or as Data URL.

fileType string: Mime type

Request Example (File)

The following request example would be used with one of the two request body examples (Plain Text or Data URL) below:

PUT /rest/v1/files/sd/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json
Content-Type: application/json
Content-Length: 196

In the request body examples below, use the FileReader's readAsText() or readAsDataURL() method to derive the fileContents value.

Plain Text Request Body: Any file with mime type "text/*", or any “brs”, “json”, “js”, “xml”, “rtf” extension, can be sent as plain text using FileReader's readAsText() method:

{
    "data": {
        "fileUploadPath": "/sd",
        "files": [
            {
                "fileName": "test.txt",
                "fileContents": "Lorem Ipsum",
                "fileType": "text/plain"
            }
        ]
    }
}

Data URL Request Body: For all other file types, including zip and media files, use the data URL format using FileReader's readAsDataURL() method:

{
    "data": {
        "fileUploadPath": "/sd",
        "files": [
            {
                "fileName": "image.png",
                "fileContents": "data:image/png;base64,DQpJbnRlcmZh.....",
                "fileType": "image/png"
            }
        ]
    }
}

Response Body

success bool: A flag that indicates if the operation succeeded or not

results string[]: The names of the files that were successfully created

Response Example (Plain Text File)

{
    "data": {
        "result": {
            "success": true,
            "results": [
                "test.txt"
            ]
        }
    },
    "route": "/v1/files/sd",
    "method": "PUT"
}

Request Example (Folder)

PUT /rest/v1/files/sd/testfolder/?destinationType=player&destinationName={{deviceSerial}}
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json

Response Example (Folder)

{
    "route": "/v1/files/sd/testfolder/",
    "method": "PUT",
    "data": {
        "result": {
            "success": true
        }
    }
}

POST /files/{:path}/

Renames a file in the path (which should include the file name)

Segment

path string: The path to the file (for example, /sd)

Request Example

POST /rest/v1/files/sd/test.txt/?destinationType=player&destinationName={{deviceSerial} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json
Content-Type: application/json
Content-Length: 57

This is the example request body:

{
    "data": {
        "name": "newname.txt"
    }
}

Response Body

The player will return a success or error message.

DELETE /files/{:path}/

Deletes a file from the player storage

Segment

path string: The path to the file (for example,/sd)

Request Example

DELETE /rest/v1/files/sd/test.txt/?destinationType=player&destinationName={{deviceSerial}} HTTP/1.1
Host: ws.bsn.cloud
Authorization: Bearer {{UserAccessToken}}
Accept: application/json, application/vnd.bsn.error+json

Response Body

The player will return a success or error message.