Skip to content

File System API

The File System Web API is a RESTful cloud API which allows basic manipulation of file system nodes (files and directories). It is intended to support web-based file system access without the need of a browser, and as such can be used in scripts with HTTP programs such as cURL.

Supported file system node operations are implemented via various HTTP request types. The File System Web API uses standard HTTP requests as well as HTTP extensions from the Web Distributed Authoring and Versioning (WebDAV) standard.

Four principal HTTP requests are implemented by the API: GET, PUT, MKCOL, and DELETE.

HTTP GET

Used to obtain, or “read”, the contents of files and directories in the file system.

URL: http://<hostname>/fs/[node]

Where node can be a file, in which case the file content is returned; or a directory, in which case an XML-formatted list of directory objects is returned.

HTTP Response Codes:

  • 200: Success
  • 404: Node not found

Example:

# curl --anyauth -k –s –u admin:PASSWORD http://192.168.0.1/fs/embedded
<!-- Automatically generated XML -->
<!DOCTYPE directorylist [
  <!ELEMENT dentry (name,size)>
  <!ELEMENT name (#CDATA)>
  <!ELEMENT size (#CDATA)>
  <!ATTLIST dentry type CDATA #IMPLIED>
  <!ATTLIST directorylist path CDATA #IMPLIED>
]>
<directorylist path = "/embedded">
  <dentry type = directory>
    <name>main</name>
    <size>0</size>
  </dentry>
  <dentry type = directory>
    <name>modem_emulation</name>
    <size>0</size>
  </dentry>
  <dentry type = directory>
    <name>monitor</name>
    <size>0</size>
  </dentry>
  <dentry type = directory>
    <name>ntp</name>
    <size>0</size>
  </dentry>
  <dentry type = directory>
    <name>query_port</name>
    <size>0</size>
  </dentry>
  <dentry type = directory>
    <name>tunnel</name>
    <size>0</size>
  </dentry>
  <dentry type = directory>
    <name>user_data</name>
    <size>0</size>
  </dentry>
</directorylist>

HTTP PUT

Used to place new files in the file system and update existing files. Directories cannot be created using PUT; the MKCOL request must be used.

Note that PUT will overwrite an existing file by the same name.

URL: http://<hostname>/fs/[path]/file

HTTP Response Codes:

  • 201: File successfully created. This code is part of the WebDAV standard.
  • 509: Not enough space
  • 500: Other failure

Example:

> ls -l
-rw-r--r-- 1 user wheel     166 Oct 22  2013 file.txt

> curl --anyauth -k –s –u admin:PASSWORD http://192.168.0.1/fs/ -T file.txt

> curl --anyauth -k –s –u admin:PASSWORD http://192.168.0.1/fs/
<!-- Automatically generated XML -->
<!DOCTYPE directorylist [
  <!ELEMENT dentry (name,size)>
  <!ELEMENT name (#CDATA)>
  <!ELEMENT size (#CDATA)>
  <!ATTLIST dentry type CDATA #IMPLIED>
  <!ATTLIST directorylist path CDATA #IMPLIED>
]>
<directorylist path = "/embedded">
  <dentry type = file>
    <name>file.txt</name>
    <size>166</size>
  </dentry>
</directorylist>

HTTP MKCOL

Used to create new directories (not files) in the file system. MKCOL (“make collection”) is an HTTP extension from the WebDAV standard.

URL: http://<hostname>/fs/[path]/directory

HTTP Response Codes:

  • 201: Directory successfully created. This code is part of the WebDAV standard.
  • 409: Directory already exists
  • 500: Other failure

Example:

> curl --digest –s –u admin:PASSWORD http://192.168.0.1/fs/dir1 -X MKCOL

> curl --digest –s –u admin:PASSWORD http://192.168.0.1/fs/
<!-- Automatically generated XML -->
<!DOCTYPE directorylist [
  <!ELEMENT dentry (name,size)>
  <!ELEMENT name (#CDATA)>
  <!ELEMENT size (#CDATA)>
  <!ATTLIST dentry type CDATA #IMPLIED>
  <!ATTLIST directorylist path CDATA #IMPLIED>
]>
<directorylist path = "/embedded">
  <dentry type = file>
    <name>file.txt</name>
    <size>166</size>
  </dentry>
  <dentry type = directory>
    <name>dir1</name>
    <size>0</size>
  </dentry>
</directorylist>

HTTP DELETE

Used to remove files and directories from the file system.

URL: http://<hostname>/fs/[path]/node

Where node can be either a file or directory.

HTTP Response Codes:

  • 204: No content (node successfully removed). This code is part of the WebDAV standard.
  • 404: Node not found
  • 500: Other failure

Example:

> curl --anyauth -k –s –u admin:PASSWORD http://192.168.0.1/fs/file.txt -X DELETE

> curl --anyauth -k –s –u admin:PASSWORD http://192.168.0.1/fs/
<!-- Automatically generated XML -->
<!DOCTYPE directorylist [
  <!ELEMENT dentry (name,size)>
  <!ELEMENT name (#CDATA)>
  <!ELEMENT size (#CDATA)>
  <!ATTLIST dentry type CDATA #IMPLIED>
  <!ATTLIST directorylist path CDATA #IMPLIED>
]>
<directorylist path = "/embedded">
  <dentry type = directory>
    <name>dir1</name>
    <size>0</size>
  </dentry>
</directorylist>