3.8 Browse

3.8.1 List top level folders

The /self User resource has a related link named <code>roots</code> (href: /self/roots) that can be used to retrieve the top level folders that are available to the authenticated user.  The response is a SearchResultsList of BinderBrief objects.

[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/self/roots

[Response]
{
  "first":0,
  "count":5,
  "total":5,
  "items":[{
    "id": -100,
    "title": "My Files",
    "path": "/Home Workspace/Personal Workspaces/David Lewis (dlewis)/Home",
    "href": "/self/my_files",
    "doc_type": "binder",
    "links": [...]
  },{
    "id": -101,
    "title": "Shared with Me",
    "href": "/self/shared_with_me",
    "doc_type": "binder",
    "links": [...]
  },{
    "id": -102,
    "title": "Shared by Me",
    "href": "/self/shared_by_me",
    "doc_type": "binder",
    "links": [...]
  },{
    "id": -103,
    "title": "Net Folders",
    "path": "/Home Workspace/Net Folders",
    "href": "/self/net_folders",
    "doc_type": "binder",
    "links": [...]
  },{
    "id": -104,
    "title": "Public",
    "href": "/self/public",
    "doc_type": "binder",
    "links": [...]
  }]

Filr has five top level folders:

  • My Files (/self/my_files)

  • Shared with Me (/self/shared_with_me)

  • Shared by Me (/self/shared_by_me)

  • Net Folders (/self/net_folders)

  • Public (/self/public)

However, not every top level folder is available to every user.  The /self/roots response will only include those that are available.

Each of the top level folders have an <code>href</code> that can be used to retrieve the BinderBrief object individually.  The /self User resource also has related links for each of the top level folders that are available to the user.

The titles of the top level folders are not localized in the response.  The English name of the folder is always returned.  Applications that are displaying the top level folders to users should localize the titles if the English name is not acceptable.

3.8.2 List folder contents (library_children)

Every Binder and BinderBrief resource has three related links that can be used to list the children of the binder:

  • library_children: retrieve all children of the binder

  • child_library_folders: retrieve the child folders of the binder

  • child_library_files: retrieve the child files of the binder

For example, the BinderBrief resource representing the "My Files" top level folder has the following related links:

{
  "id": -100,
  "title": "My Files",
  "links": [{
    "rel": "library_children",
    "href": "/self/my_files/library_children"
  },{
    "rel": "child_library_folders",
    "href": "/self/my_files/library_folders"
  },{
    "rel": "child_library_files",
    "href": "/self/my_files/library_files"
  }]
}

So, to list all of the children of the My Files folder, you find the "library_children" related link (href: "/self/my_files/library_children") and make a GET request for that resource.  The response is a SearchResultList of SearchableObjects (BinderBrief objects to represent the folders and FileProperties objects for files).

[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/self/my_files/library_children

[Response]
{
  "first":0,
  "count":24,
  "total":24,
  "items":[{
    "id": 48,
    "doc_type": "binder",
    "entity_type": "folder",
    "href": "/folders/48",
    "parent_binder": {
      "href": "/self/my_files",
      "id": -100
    },
    "title": "A",    
    "path": "/Home Workspaces/Personal Workspaces/David Lewis (dlewis)/Home/A",
    "links": [{
      "rel": "library_children",
      "href": "/folders/48/library_children"
    },{
      "rel": "child_library_folders",
      "href": "/folders/48/library_folders"
    },{
      "rel": "child_library_files",
      "href": "/folders/48/library_files"
    }]
  },{
    "id": "09c1c3fb5256e2e4015256e8691c003b",
    "doc_type": "file",
    "href": "/files/09c1c3fb5256e2e4015256e8691c003b/metadata",
    "parent_binder": {
      "href": "/self/my_files",
      "id": -100
    },
    "name": "test.txt",
  },
  ...22 more results...
  ]
}

Notice that the BinderBrief resource representing the child folder named A also has "library_children", "child_library_folders" and "child_library_files" related links.  Those links can then be used to list the children of folder A:

[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folders/48/library_children

[Response]
{
  "first": 0,
  "count": 12,
  "total": 12,
  "items": [...]
}

Paged Results

Most of the library_children resources only return the first 100 results.  The SearchResultList response indicates how many children were returned (the "count" field) and the total number of children in the folder (the "total" field).  If a partial list is returned, the SearchResultList will also include a "next" field containing an Href that can be used to retrieve the next page of children.  This is done using "first" and "count" query parameters.

[Request]
> curl -k -u dlewis:novell \
  https://amethyst.provo.novell.com:8443/rest/self/my_files/library_children?count=20

[Response]
{
  "first":0,
  "count":20,
  "total":24,
  "next":"/self/my_files/library_children?first=20&count=20",
  "items":[...First 20 results...]
}

[Request]
> curl -k -u dlewis:novell \
  "https://amethyst.provo.novell.com:8443/rest/self/my_files/library_children?first=20&count=2"

[Response]
{
  "first":20,
  "count":4,
  "total":24,
  "items":[...Last 4 results...]
}

The /shares/*/library_children, /shares/*/library_folders and /shares/*/library_files resources do not support the "first" and "count" query parameters.  All results are returned regardless of the values specified by "first" and "count".

Listing multiple binders at once

The root resource has a "binder_library_children" related link that can be used to list the children of multiple binders in a single request:

[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest

[Response]
{
  "links":[ 
    ...
    {
      "rel": "binder_library_children",
      "href": "/binders/library_children",
    },
    ...
}

The "binder_library_children" resource allows you to specific a number of binder IDs using the "id" query parameter.  It supports top level folder IDs (-100, -101, etc.) as well as regular folder IDs (48, 103, 567).  The response is a list of BinderChildren objects.

[Request]
> curl -k -u dlewis:novell \
  "https://amethyst.provo.novell.com:8443/rest/binders/library_children?id=-100&id=48&id=49&count=10"

[Response]
[{
  "binder_id": 49,
  "children": {
    "first": 0,
    "count": 2,
    "total": 2,
    "items": [...2 children...]
  }
},{
  "binder_id": 48,
  "children": {
    "first": 0,
    "count": 8,
    "total": 12,
    "items": [...8 children...]
}]         

 The "count" query parameter specifies the total number of children to return.  In this case, 10 results were returned: both children of folder 49 and the first 8 children of folder 48.  The following illustrates how to retrieve the next 10 results:

[Request]
> curl -k -u dlewis:novell \
  "https://amethyst.provo.novell.com:8443/rest/binders/library_children?\
   id=-100&id=48&count=10&first_id=48&first=8"

[Response]
[{
  "binder_id": 48,
  "children": {
    "first": 8,
    "count": 4,
    "total": 12,
    "items": [...4 children...]
  }
},{
  "binder_id": -100,
  "children": {
    "first": 0,
    "count": 6,
    "total": 24,
    "items": [...6 children...]
}] 

Folder 49 was removed from the request because the previous request returned all of the results.  Since the order of the IDs is non-deterministic, the "first_id=48" parameter indicates that folder 48 should be processed first, and the "first=8" parameter specifies that the results should begin with the 9th child of folder 49 (the indexing is 0-based).  The response contains the final 4 results of folder 48 and the first 6 results of folder -100.

To get the next 10 results, the query parameters would be "id=-100&first_id=-100&first=6&count=10".

Last-Modified/If-Modified-Since

The "library_children", "library_folders" and "library_files" resources support the "If-Modified_Since" HTTP header.  The -v curl option displays verbose information, including request and response headers.

[Request]
> curl -v -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folders/48/library_children

[Response]
> GET /rest/folders/48/library_children HTTP/1.1
> Authorization: Basic ****
> User-Agent: curl/7.35.0
> Host: amethyst.provo.novell.com:8443
> Accept: */*
> 
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Last-Modified: Thu, 11 Feb 2016 17:46:28 GMT
< Content-Type: application/json
< Transfer-Encoding: chunked
< Date: Fri, 19 Feb 2016 05:45:02 GMT
< 
{
  "first": 0,
  "count": 12,
  "total": 12,
  "items": [...]
}

The "Last-Modified" response header indicates the time when the list of children last changed.  If you make that same request, but include this time in the "If-Modified-Since" request header, the server will return an HTTP 304 Not Modified response with no response body.

[Request]
> curl -v -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folders/48/library_children \
  -H "If-Modified-Since: Thu, 11 Feb 2016 17:46:28 GMT"

[Response]
> GET /rest/folders/48/library_children HTTP/1.1
> Authorization: Basic ****
> User-Agent: curl/7.35.0
> Host: amethyst.provo.novell.com:8443
> Accept: */*
> If-Modified-Since: Thu, 11 Feb 2016 17:46:28 GMT
> 
< HTTP/1.1 304 Not Modified
< Server: Apache-Coyote/1.1
< Date: Fri, 19 Feb 2016 05:48:21 GMT
< 

If the list of children has changes after the date in the "If-Modified-Since" header, the response will contain the full list of children, or the full page of children as specified by the "first" and "count" query parameters.

[Request]
> curl -v -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folders/48/library_children
  -H "If-Modified-Since: Thu, 11 Feb 2016 17:46:28 GMT"

[Response]
> GET /rest/folders/48/library_children HTTP/1.1
> Authorization: Basic ****
> User-Agent: curl/7.35.0
> Host: amethyst.provo.novell.com:8443
> Accept: */*
> 
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Last-Modified: Thu, 18 Feb 2016 14:23:54 GMT
< Content-Type: application/json
< Transfer-Encoding: chunked
< Date: Fri, 19 Feb 2016 05:45:02 GMT
< 
{
  "first": 0,
  "count": 13,
  "total": 13,
  "items": [...all 13 children...]
}