Upload Files to User's Storage Area

Use the POST /files transaction to upload a file, multiple files, or a zipped archive to the user's storage area.

• Method: POST
• Target: https://api.ensims.com/users/api/files{/target/folder}
• Cookies: JWT session token
• Header: none
• Body: a file or files to upload
• Success: Transaction return object
• Failed: HTTP 401 - Unauthorized; HTTP 500 - Internal error

There are a number of uses of the upload transaction.

To upload one file to the root of the user's upload area, use the API's endpoint URL without any additional paths, i.e. https://api.ensims.com/users/api/files. Here is the example using cURL:

curl -b .cookies/cookies -F 'file=@test123.txt' https://api.ensims.com/users/api/files

The -F option adds the required “multipart/form-data” encoding type to the request, whereas the file=@/paht/to/file specify which file to upload. Please note the field name must be file for the service to accept the upload.

If successful, a successful transaction response as below will be returned. Details of the fields in the confirmation object are explained here.

{
  "ok" : true,
  "status" : "File(s) uploaded successfully",
  "fileHandle" : "",
  "callback" : "/users/api/files/"
}

To upload one file to a specific folder in the user's upload area, use the API's endpoint URL with the full path to the target folder, e.g. https://api.ensims.com/users/api/files/test/today. This will upload the file to the folder named /test/today/ in the user's upload area. If the folder does not exist, it will be created.

Here is the example using cURL:

curl -b .cookies/cookies -F 'file=@test123.txt' https://api.ensims.com/users/api/files/test/today

The -F option adds the required “multipart/form-data” encoding type to the request, whereas the file=@/paht/to/file specify which file to upload. Please note the field name must be file for the service to accept the upload.

If successful, a successful transaction response as below will be returned. Details of the fields in the confirmation object are explained here.

{
  "ok" : true,
  "status" : "File(s) uploaded successfully",
  "fileHandle" : "test/today",
  "callback" : "/users/api/files/test/today"
}

To upload multiple files to a specific folder in the user's upload area, use the API's endpoint URL with the full path to the target folder, e.g. https://api.ensims.com/users/api/files/test/today. This will upload the files to the folder named /test/today/ in the user's upload area. If the folder does not exist, it will be created. All files to be uploaded have the same field name file.

Here is the example using cURL:

curl -b .cookies/cookies -F 'file=@test123.txt' -F 'file=@test456.txt' -F 'file=@test789.txt' https://api.ensims.com/users/api/files/test/today

The multiple -F options with the file=@/paht/to/file1 do the trick. Please note if any files already exist in the target folder, it will be overwritten.

If successful, a successful transaction response as below will be returned. Details of the fields in the confirmation object are explained here.

{
  "ok" : true,
  "status" : "File(s) uploaded successfully",
  "fileHandle" : "test/today",
  "callback" : "/users/api/files/test/today"
}

Pack the files in a zipped archive may make uploading easier and quicker. Also, you can include the folder structure of the files to upload. Once received, the ENSIMS Web service will unpack the files, including any folder structure, to the target folder in the user's upload area, and return the base folder of the uploaded files.

The syntax of the upload transaction is the same as uploading a single file, e.g.:

curl -b .cookies/cookies -F 'file=@tests.zip' https://api.ensims.com/users/api/files/test/zipped

If successful, a successful transaction response as below will be returned. Details of the fields in the confirmation object are explained here.

{
  "ok" : true,
  "status" : "File(s) uploaded successfully",
  "fileHandle" : "test/zipped",
  "callback" : "/users/api/files/test/zipped"
}

A successful transaction return object contains the status flag and a message as well as the location of where the uploaded files are stored, such as the example below.

{
  "ok" : true,
  "status" : "File(s) uploaded successfully",
  "fileHandle" : "test/today",
  "callback" : "/users/api/files/test/today"
}

The fileHandle and the callback fields both point to the location (folder in the upload area) where the uploaded files are stored. They can be used for subsequent access to the uploaded files. If a zip archive is uploaded, its contents will be expanded on the server and the filehandle points to the base folder of the archive.

An HTTP 401 - Unauthorized response will be received if the existing token is invalid.

An HTTP 500 - Server error response will be received if the request is malformed or cannot be processed for some reasons.

Make sure Requests is correctly installed in your Python environment, and the session token has been stored in the cookies variable after successfully logging on to the service. Run the following lines for uploading various files to different locations in the user's upload area.

import requests

# Upload one file to root
files = {'file': open('test123.txt', 'rb')}
r = requests.post('https://api.ensims.com/users/api/files', files=files, cookies=cookies)

# Upload one file to a target folder
files = {'file': open('test123.txt', 'rb')}
r = requests.post('https://api.ensims.com/users/api/files/test/today', files=files, cookies=cookies)

# Upload multiple files to a target folder, including different file types and customizable target file names
files = [
    ('file', ('5ZoneAirCooled-v93.idf', open('job_example\\5ZoneAirCooled-v93.idf', 'rb'), 'text/plain')),
    ('file', ('in.epw', open('job_example\\in.epw', 'rb'), 'text/plain'))
]
r = requests.post('https://api.ensims.com/users/api/files/test/eplus', files=files, cookies=cookies)

# Upload files in a zip archive to a target folder
files = {'file': open('job_example\\Shoebox_v8.9.zip', 'rb')}
r = requests.post('https://api.ensims.com/users/api/files/test/eplus', files=files, cookies=cookies)


# Show return info
r.json()