Upload API (V1)
The upload API allows you to upload from other clients than the Sitecore Content Hub™ web UI. For example, it allows you to use Sitecore Connect™ for Creative Cloud™.
The upload API exposes the following endpoints:
api/v1.0/upload
: requests an upload URL.api/v1.0/upload/assets
: uploads (creates) a new asset from an already uploaded file.api/v1.0/upload/assets/{id}
: uploads a master file of an existing asset.api/v1.0/upload/assets/{id}/alternative
: uploads an alternative file of an existing asset.
A complete upload flow consists of three steps:
- Request an upload URL
- Upload a file to the received URL
- Upload or create a new asset or update an existing one with a master or alternative file
Request an upload URL
To retrieve an upload URL, send a POST
request to the endpoint api/v1.0/upload
.
The request form body must contain the following fields:
fileName
- name of the file to upload.fileSize
- size of the file to upload.
A successful response returns the upload URL in the location header, and a JSON body containing information structured as follows:
{
"fileIdentifier": "azr123grz3",
"storageIdentifier": "weu"
}
- The
fileIdentifier
represents the identifier of the file in the system. - The
storageIdentifier
represents the location where the file is stored. It can be null or missing in the JSON.
The upload URL constantly points to an Azure storage blob.
In case of a distributed upload, the API endpoint api/v1.0/upload
of the portal application redirects you to the traffic manager and the satellite closest to you creates and returns an upload URL.
Upload a file to the received URL
The received upload URL is a public URL to an Azure storage blob, which means that you can upload files using the Azure blob service REST API.
To perform an upload, send a PUT
request to the upload URL with the following required headers:
x-ms-blob-type
: Azure expects the value to be BlockBlob.x-ms-blob-content-type
: the content-type of the file.x-ms-meta-Filename
: the name of the file.
Upload a large file to Azure blob storage
If the file is bigger than 200 MB, split it and send each block separately to Azure by extending the upload URL with the query string parameters comp=block&blockid={blockid}
:
blockid
is a valid Base64 string value to identify the block.- For a given blob, the length of the specified
blockid
value must be the same size for each block.
When all the blocks are sent, send another request to the upload URL to notify that the upload is complete, and that all the blocks should be put together:
- Extend the upload URL with the query string parameter
comp=blocklist
. - The body of the request must be XML formatted and must specifies in which order to load the blocks using their
blockid
.
The following code snippet shows how to load blocks using blockid:
<?xml version="1.0" encoding="utf-8"?>
<BlockList>
<Latest>AAAAAA==</Latest>
<Latest>AQAAAA==</Latest>
<Latest>AZAAAA==</Latest>
</BlockList>
This final request requires the following headers:
x-ms-blob-content-type
: the content-type of the file.x-ms-meta-Filename
: the specific name of the file.
Note
For more information, see the Azure put block documentation. Additionally, you can use the JavaScript Azure SDK to perform the previously described actions.
Upload or create a new asset or update existing one with master or alternative file
To create a new asset from an uploaded file, send a POST
request to api/v1.0/upload/assets
.
To upload a master file of an existing asset, send a POST
request to api/v1.0/upload/assets/{id}
with the id of the asset.
To upload an alternative file of an existing asset, send a POST
request to api/v1.0/upload/assets/{id}/alternative
with the id of the asset.
Important
In all cases, the request body must contain the JSON content received previously.
Upload configurations
The uploads are processed by using an upload configuration. Upload configurations may include:
- maximum allowed file size, which limits the size of files allowed for upload.
- disallowed extensions, which defines the file extensions not allowed for upload.
- DefaultUploadConfiguration, which defines the default configuration.
Note
Superusers can override the Repository and Life Cycle of Created Assets upload settings using the ApiUploadConfigurationsetting. To modify this setting, click Manage and, on the Manage page, click Settings. Under ProtalConfiguration, select ApiUploadConfigurationsetting.
Can we improve this article ? Provide feedback