CreateChildContainer

Required for

iOS Android

POST /wopi/containers/(container_id)

The CreateChildContainer operation creates a new child container in the provided parent container.

The CreateChildContainer operation has two distinct modes: specific and suggested. The primary difference between the two modes is whether the WOPI client expects the host to use the container name provided exactly (specific mode) or if the host can adjust the container name in order to make the request succeed (suggested mode).

Hosts can determine the mode of the operation based on which of the mutually exclusive X-WOPI-RelativeTarget (indicates specific mode) or X-WOPI-SuggestedTarget (indicates suggested mode) request headers is used. The expected behavior for each mode is described in detail below.

Parameters
  • container_id (string) – A string that specifies a container ID of a container 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.

Request Headers
  • X-WOPI-Override – The string CREATE_CHILD_CONTAINER. Required.

  • X-WOPI-SuggestedTarget

    A UTF-7 encoded string that specifies a full container name. Required.

    The response to a request including this header must never result in a 400 Bad Request or 409 Conflict. Rather, the host must modify the proposed name as needed to create a new container that is legally named.

    This header must be present if X-WOPI-RelativeTarget is not present; the two headers are mutually exclusive. If both headers are present the host should respond with a 501 Not Implemented.

  • X-WOPI-RelativeTarget

    A UTF-7 encoded string that specifies a full container name. The host must not modify the name to fulfill the request.

    If the specified name is illegal, the host must respond with a 400 Bad Request.

    If a container with the specified name already exists, the host must respond with a 409 Conflict. When responding with a 409 Conflict for this reason, the host may include an X-WOPI-ValidRelativeTarget specifying a container name that is valid.

    This header must be present if X-WOPI-SuggestedTarget is not present; the two headers are mutually exclusive. If both headers are present the host should respond with a 501 Not Implemented.

Response Headers
  • X-WOPI-InvalidContainerNameError – A string describing the reason the CreateChildContainer operation could not be completed. This header should only be included when the response code is 400 Bad Request. This string is only used for logging purposes.

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 CreateChildContainer call is JSON (as specified in RFC 4627).

All optional values default to the following values based on their type:

Type

Default value

Boolean

false

String

The empty string

Integer/Long

Varies; see individual properties for details

Array

Empty array

Important

No properties should be set to null. If you do not wish to set a property, simply omit it from the response and WOPI clients will use the default value.

Required response properties

The following properties must be present in all CreateChildContainer responses:

ContainerPointer

A JSON-formatted object 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.

Other response properties

ContainerInfo

Hosts can optionally include the ContainerInfo property, which should match the CheckContainerInfo response for the newly created container.

If not provided, the WOPI client will call CheckContainerInfo to retrieve it. Including this property in the response is strongly recommended so that the WOPI client does not need to make an additional call to CheckContainerInfo.

Sample response

{
  "ContainerPointer" : {
    "Url" : "http://.../wopi*/containers/<containerId>?access_token=<per_container_token>",
    "Name" : "Container Name"
  },
  "ContainerInfo" : {
    "Name" : "Container Name",
    "HostUrl" : "",
    "SharingUrl" : "",
    "UserCanCreateChildContainer" : false,
    "UserCanCreateChildFile" : false,
    "UserCanDelete" : false,
    "UserCanRename" : false
  }
}