EnumerateAncestors (files)

Required for

iOS Android

GET /wopi/files/(file_id)/ancestry
Parameters
  • file_id (string) – A string that specifies a file ID of a file managed by host. This string must be URL safe.

Query Parameters
  • access_token (string) – An access token that the host will use to determine whether the request is authorized.

Response Headers
  • X-WOPI-EnumerationIncomplete

    An optional header indicating that the enumeration of the container’s ancestry is incomplete. If set, the value of this header must be the string true.

    A WOPI client may choose to issue additional EnumerateAncestors requests to complete the enumeration.

Status Codes

See also

Standard WOPI request and response headers

In addition to the request/response headers listed here, this operation may also use the Standard WOPI request and response headers.

Response

The response to a EnumerateAncestors call is JSON (as specified in RFC 4627) containing the following required properties:

AncestorsWithRootFirst

An array of JSON-formatted objects containing the following properties:

Name

The name of the container without a path. This value should match the Name property in a CheckContainerInfo response. Required.

Url

A URI to the container, including a valid access token. Required.

Danger

This property includes an access token and thus has important security implications. See Preventing ‘token trading’ for more details.

The array must always be ordered such that the ancestor closest to the root is the first element.

If there are no ancestor containers, this property should be an empty array.

Sample response

Consider a file in the following container hierarchy: /root/grandparent/parent/myfile.docx. When called on this file, the EnumerateAncestors operation should return the following:

{
  "AncestorsWithRootFirst": [
    {
      "Url": "http://.../wopi*/containers/<containerId>?access_token=<per_container_token>",
      "Name": "root"
    },
    {
      "Url": "http://.../wopi*/containers/<containerId2>?access_token=<per_container_token2>",
      "Name": "grandparent"
    },
    {
      "Url": "http://.../wopi*/containers/<containerId3>?access_token=<per_container_token3>",
      "Name": "parent"
    }
  ]
}