EnumerateAncestors (files)

Article
03/04/2023

iOS and Android Desktop

The EnumerateAncestors operation represents an ancestry file or folder being operated on via WOPI operations. A host must issue a unique ID for any file used by a WOPI client. The client will, in turn, include the file ID when making requests to the WOPI host. Thus, a host must be able to use the file ID to locate a particular file. For more information on File ID strings and requirements for integration, see Key concepts.

Note

EnumerateAncestors (containers)

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 uses 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 might choose to issue additional EnumerateAncestors requests to complete the enumeration.

Status codes

200 OK – Success.
401 Unauthorized – Invalid access token.
404 Not Found – Resource not found or user unauthorized.
500 Internal Server Error – Server error.
501 Not Implemented – Operation not supported.

In addition to the request and response headers listed here, this operation might also use the Standard WOPI request and response headers. For more information see Standard WOPI request and response headers.

Response

The response to a EnumerateAncestors call is JSON 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. This value is required.
- Url - A URL to the container, including a valid access token. This property is required.
Caution

This property includes an access token so it 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.

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"
    }
  ]
}
```

Share via