Expand Container

Extracts the contents of a container file.

The Expand Container API extracts content from container files (that is, files that contain a set of other files, such as ZIP or TAR archives, and PST files). For a full list of supported container formats, see Supported Formats.

The API extracts the files from the container file and stores them for use in other APIs. It returns a list of the file names and object store references of the files that it extracts from the container. You can pass these references to other APIs to process the stored files (in the same way as you use references that you store by using the Store Object API).

Quick Start

The API extracts the files from the container file and returns a reference.

curl -X POST http://api.havenondemand.com/1/api/[async|sync]/expandcontainer/v1 --form "file=@myzip.zip"

{
  "files": [
    {
      "name": "myfolder/worksheet.xls",
      "reference": "e04beffc-ec71-4f6f-9d25-2ff988c8ab3c"
    },
    {
      "name": "myfolder/document.doc",
      "reference": "dbb35d16-7481-4938-961d-d38202513838"
    },
    {
      "name": "myfolder/javascript.js",
      "reference": "7412cab6-3068-4eb4-aead-854f86fe8f52"
    },
    {
      "name": "myfolder/otherzip.zip",
      "reference": "abb46d16-3441-4234-912e-f32202513839"
    }
}

Note: API input is subject to a maximum size quota. If you upload text or a file that is too large, the API returns an error. For more information, see Rate Limiting, Quotas, Data Expiry, and Maximums.

After you use the Expand Container API to extract files, you can use the object store references as an input for any other API that accepts a file as input. The following example sends the extracted reference for the document.doc file to the Sentiment Analysis API.

/1/api/[async|sync]/analyzesentiment/v1?reference=dbb35d16-7481-4938-961d-d38202513838

Note: You cannot download the extracted files from the Expand Container API.

By default, the API extracts files only from the container provided (not any child container files). If you want to expand child containers, you can set the depth parameter. This parameter controls the number of levels to which to expand the child container files. The following example expands the submitted file, and any child containers (but no further child containers):

curl -X POST http://api.havenondemand.com/1/api/[async|sync]/expandcontainer/v1 --form "file=@myzip.zip" --form "depth=1"

If there are further child container files, you can pass these files to the Expand Container API for further extraction by using their extracted reference. The following example sends the reference for otherzip.zip from the first example above:

/1/api/[async|sync]/expandcontainer/v1?reference=abb46d16-3441-4234-912e-f32202513839

Synchronous
https://api.havenondemand.com/1/api/sync/expandcontainer/v1
Asynchronous
https://api.havenondemand.com/1/api/async/expandcontainer/v1
Authentication

This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Required
Name Type Description
file
binary The container file to expand.
reference
string A Haven OnDemand reference obtained from either the Expand Container or Store Object API. The corresponding container file is passed to the API.
url
string A publicly accessible HTTP URL from which the container file can be retrieved.
Optional
Name Type Description
depth
number The maximum depth to which to expand nested containers. It cannot be more than five. Values higher than five are truncated.
password
array<string> Passwords to use to extract the files. This parameter is masked.

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Expand Container Response {
files ( array[Files] ) A list of files and object store references.
}
Expand Container Response:Files {
One of the following: Files_1 or Files_2
name ( string ) The name of the extracted file.
}
Files_1 {
reference ( string ) The object store reference of the extracted file.
}
Files_2 {
error ( Error ) Error extracting this file.
}
Files_2:Error {
error ( integer ) Error code.
reason ( string ) Error message.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "properties": {
        "files": {
            "items": {
                "oneOf": [
                    {
                        "properties": {
                            "reference": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "reference"
                        ]
                    },
                    {
                        "properties": {
                            "error": {
                                "properties": {
                                    "error": {
                                        "type": "integer"
                                    },
                                    "reason": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "error",
                                    "reason"
                                ],
                                "type": "object"
                            }
                        },
                        "required": [
                            "error"
                        ]
                    }
                ],
                "properties": {
                    "name": {
                        "type": "string"
                    }
                },
                "required": [
                    "name"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "required": [
        "files"
    ],
    "type": "object"
}
https://api.havenondemand.com/1/api/sync/expandcontainer/v1
/api/api-example/1/api/sync/expandcontainer/v1
Examples
See this API for yourself - select one of our examples below.
Expand ZIP
Expand TAR
Expand PST
Parameters
Required
Select file Change Remove
Optional
Name Type Value
depth
number
password
array
Add another value


Async – Response An error occurred making the API request
Response Code:
Response Body

	
Making API Request…
Checking result of job

To try this API with your own data and use it in your own applications, you need an API Key. You can create an API Key from your account page - API Keys.

Output Refresh An error occurred making the API request View Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

			
Make this call with curl


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.