JSON view of a folder

The contents of a folder within a filespace can be returned (in json) by sending an HTTP GET request to the JSON view API. For example, to view the contents of the top-level Files folder in the filespace: https://files.warwick.ac.uk/sarah, we can send a request to:

https://files.warwick.ac.uk/files/api/browsefilesjson?forceBasic=true&path=sarah/Files

Note that only the path to the filespace/folder is specified - not the entire URL.

Similarly, to retrieve the contents of a specific folder at https://files.warwick.ac.uk/sarah/web will be something like:


jo-dev-oracle$ curl -i -u usercode "https://files.warwick.ac.uk/files/api/browsefilesjson?forceBasic=true&path=sarah/Files/web"

Enter host password for user 'usercode':

HTTP/1.1 200 OK
Date: Wed, 21 Nov 2012 11:56:49 GMT
Server: Apache-Coyote/1.1
X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
Content-Type: text/json;charset=UTF-8
Content-Language: en-GB
Content-Length: 519
Set-Cookie: hashTag=""; Domain=.warwick.ac.uk; Expires=Thu, 01-Jan-1970 00:00:10 GMT; Path=/
Vary: User-Agent

{"folder":{"name":"web","domain":"files.warwick.ac.uk","isRoot":"false","path":"statuschecker/Files/web","shortPath":"web","account":"statuschecker","parentPath":"statuschecker/Files","parentShortPath":"","files":[{"id":"094d42c52ee75b8f012ee76e0b0d000c","extension":"txt","extensionName":"Text file","size":"1 KB","path":"web/test1.txt","name":"test1.txt"},{"id":"094d42c52ee75b8f012ee76e0be3000f","extension":"txt","extensionName":"Text file","size":"1 KB","path":"web/test2.txt","name":"test2.txt"}],"folders":[]}}

N.B. If the request is successful, a 200 will be returned. A 500 HTTP Response will be returned in case of error (e.g. a folder of that name doesn't exist at that location). A 302 will be returned in case of insufficient permissions.

Important: Because of the way that HTTP Basic authentication sends an encrypted version of the username and password with every request, it is less secure than standard authentication through web sign-on. As well as this, by their very nature, automated programs require username and passwords to be stored on a computer in such a way that it would be a breach of the Terms and Conditions of IT Services accounts to store your actual ITS usercode and password in this way.

For automated systems that access Sitebuilder APIs, you must use an external user account for API access. You should not share an API account between multiple systems, and you should ensure that each account is granted the minimal permissions it needs to perform its tasks, and only on the pages where it needs to perform these tasks.

Getting an external user account for API access

In order to obtain an external user account for API access, please email webteam at warwick dot ac dot uk