upload_multipart

Resource functions

Collection functions

Search functions

IIIF

IIIF

Metadata functions

User functions

System

Message functions

get_user_message

Plugin functions

Uploads files using HTTP multipart to an existing resource, replacing any file that is already attached.

Variable	Description	Data type	Default
$ref *	The ID of the resource.	integer	N/A
$no_exif *	Do not process embedded metadata.	boolean	N/A
$revert *	Do not upload a new file, but re-process the existing file as if it has been uploaded again. Useful for re-processing embedded metadata, e.g. after changing the field mappings.	boolean	N/A
$previewonly	Replace preview image only (must upload a JPG file)	boolean	false
$alternative	Use the uploaded file to replace the alternative file with the given ID. Note that api_add_alternative_file() must be called first if creating a new alternative file. If an $alternative identifier is specified then $previewonly is ignored and set to false	integer	0
$file *	The file to upload. This must be included in the POST as multipart/form-data. not passed to the function. Important: do not use the file as part of the signature!	binary	N/A

Response

If successful, a 204 HTTP status will be returned, otherwise different HTTP statuses with a payload message describing the issue.

Examples

General error (HTTP status - 500):

Array
(
    [status] => fail
    [data] => Array
        (
            [message] => An error occurred while uploading the file.
        )
)

File size too big error (HTTP status - 413):

Array
(
    [status] => fail
    [data] => Array
        (
            [message] => The maximum allowed upload file size is 5M.
        )
)

Duplicate file (HTTP status - 400):

Array
(
    [status] => fail
    [data] => Array
        (
            [message] => Duplicate file upload, file matches resources: 8
        )
)

Note: this requires checksums to be enabled.

Request example

PHP

// Set the username and private API key (from the user account page) for the user making the API call.
$user = "your username";
$private_key = "your users' private key";
$url = "https://my.resourcespace.system/api/";

// Formulate the API binding (function) query data.
// NOTE: Boolean values may need to be passed as integers: 1 / 0
$data = array(
    'user'  => $user,
    'function'  => 'upload_multipart',
    'ref' => 8,
    'no_exif' => true,
    'revert' => false,
    );

// Sign the query using the private key.
$sign = hash('sha256', $private_key . http_build_query($data));

// This part simply replicates the GET query string to be POSTed as a single 'query' POST item.
$data['sign'] = $sign;
$postdata = [
    'query' => http_build_query($data),
    'sign' => $sign,
    'user' => $user,
    'file' => new CURLFile('/path/to//file.ext'), # IMPORTANT: this wasn't part of the signature!
];

$curl = curl_init($url);
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type: multipart/form-data']);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1 );

// Make the request and output the results.
$curl_response = curl_exec($curl);
print_r(json_decode($curl_response));

cURL

# Generate the signature for the request
echo -n "yourPrivateKeyuser=yourUsername&function=upload_multipart&ref=1126&no_exif=1&revert=0" | sha256sum
curl \
    -F 'query="user=yourUsername&function=upload_multipart&ref=1126&no_exif=1&revert=0"' \
    -F 'sign="yourGeneratedSignature"' \
    -F 'user="yourUsername"' \
    -F "file=@/path/to/file.ext" \
    'https://localhost/trunk/api/'

Knowledge Base