WHFS API

Files and folders in the Publisher are considered 'WHFS Objects' and are accessed through the /whfs/object endpoint:

Some curl examples:

# List the root in the publisher
curl -H"Authorization: bearer $APITOKEN" "${BACKENDURL}.wh/api/v1/whfs/object?children=true"
# You will see the list of root folders (and files) in the `children` attribute of the response.

# List the contents of the repository site (assuming it's still in the root)
curl -H"Authorization: bearer $APITOKEN" "${BACKENDURL}.wh/api/v1/whfs/object?path=/Repository&children=true"

# Get the contents of RTD document 'publications' in folder '/WebHare test/'
curl -H"Authorization: bearer $APITOKEN" "${BACKENDURL}.wh/api/v1/whfs/object?path=/WebHare%20test/publications&instances=*"

A RTD document has the following structure (irrelevant JSON parts are left out):

{
  "name": "publications",
  "type": "platform:filetypes.richdocument",
  "instances": [
    {
      "whfsType": "platform:virtual.objectdata",
      "data": {
        "title": "",
        "description": "",
        "keywords": "",
        "publish": true
      }
    },
    {
      "whfsType": "platform:filetypes.richdocument",
      "data": {
        "data": [ .... ]
      }
    }
  ]
}

Instances hold the actual data and would normally be accessed using GetInstanceData/SetInstanceData in HareScript. (platform:filetypes.richdocument is a shorter name for the http://www.webhare.net/xmlns/publisher/richdocumentfile type)

Instances consist of a whfsType member holding the type, and a data member holding actual data members. You can find the structure of existing instance types in the Dashboard (under Publisher > Content types)

A richdocument has a data member of type 'richdocument' holding the actual document. See the (RTD JSON Format)[rtd-json-format] for more details. (Note that in the API the RTD content is in a property data of another property named data)

The API also offers an instance of type platform:virtual.objectdata which contains the metadata fields of the object itself (the properties normally found in system.fs_objects). You cannot access this instance type in HareScript or JavaScript, it exists purely to display these properties in the API

Writing to WHFS

To create new objects, POST to the parent path:

# Create a folder 'new folder' in '/Webhare test'
curl -H"Authorization: bearer $APITOKEN" \
     -H"Content-type: application/json" \
     -d'{"name":"new folder","type":"platform:foldertypes.default"}' \
     "${BACKENDURL}.wh/api/v1/whfs/object?path=/WebHare%20test" 

# Create a RTD 'new doc' in '/Webhare test/new folder'
curl -H"Authorization: bearer $APITOKEN" \
     -H"Content-type: application/json" \
     -d'{ "name":"new doc",
          "type":"platform:filetypes.richdocument",
          "instances": [{
            "whfsType": "platform:virtual.objectdata",
            "data": {
              "title": "My new document",
              "publish": true 
            }
          }, {
            "whfsType": "platform:filetypes.richdocument",
            "data": {
              "data": [
                { "tag": "h1", "items": [ "My first document" ] },
                { "tag": "p", "items": [ "Hello World!" ] } 
              ]
            }
          }]
        }' \
     "${BACKENDURL}.wh/api/v1/whfs/object?path=/WebHare%20test/new%20folder"

To update an existing object, PUT to its path. The instances will be merged with any existing instances and only explicitly specified top-level members are overwritten. Eg if you submit

          "instances": [{
            "whfsType": "platform:virtual.objectdata",
            "data": {
              "title": "My new document",
            }
           ]

The description, keywords and publish fields are not overwriten.

PreviousNext