CreateChildContainer

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. We'll describe the expected behavior for each mode 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

• 200 OK – Success

• 400 Bad Request – Specified name is illegal

• 401 Unauthorized – Invalid access token

• 404 Not Found – Resource not found/user unauthorized

• 409 Conflict – Target container already exists

• 500 Internal Server Error – Server error

• 501 Not Implemented – Operation not supported

Note

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.

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; WOPI clients will use the default value in these cases.

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.

  Caution

  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
    }
  }