In order to upload a media item via AdmiralCloud’s Dropsites, please follow this guide.
First you have to consider if you want to make a plain upload or if you want to use some additional functions like adding tags or metadata. The latter requires an authentication process.
Before you start, make sure to that you have a device identifier. If you don’t have one, please create one or fetch one using TBC. Set the appropriate header for X-AdmiralCloud-Device.
Step 1 – Dropsite delivery
The first step is to fetch the dropsite content using Deliver Dropsite call.
If you want to upload files without additional metadata like tags continue with step 3.
The response contains a clientId and a code that needs to be exchanged for a token. Please note, that this code has a limited timespan.Make sure to set the clientId header based on the one you obtain from the response.
Step 2 – Generate token (optional)
Just prior to the upload, and only then, you should exchange the code for the token. If the code has expired please make the Dropsite deliver call again and retrieve a fresh code. If you request the dropsite token for the first time, you can decide whether to use the real user data for email, firstname and lastname or to generate random user data. The email address will returned and should be stored in your browser. This way subsequent Dropsite uploads will be linked to the same user.
If you already have an email address stored, just send it with the generate token request and the AdmiralCloud API will identify your user and return the appropriate session.
Please note, that session tokens have a limited timespan. Make sure to request a fresh token before this one times out. Please also note, that the session will be invalidated after you make the uploadComplete call.
Before you continue, make sure to set the provided access token as bearer header.
Step 3 – Create an upload document
Use dropsite.createUpload call to initiate an upload. The response contains temporary credentials, a bucket and S3 key for every media item you want to upload.
If you have sent an identifier (uuid) for every media to upload (which is recommended) this identifier is sent back with the response. This way you can map your sent payload with the response. Keep in mind that the payload order might be different for request and response!
If you send a valid userId (as creatorId) and email, e.g. from “generate token” call above or any other previously authenticated call, the newly uploaded mediacontainer will be created with that id as creatorId. This way it is easy to find uploaded mediacontainer from a given person
If we find duplicates for a requested upload/file you will see that in the response and can decide if you want to upload that file nevertheless.
Make sure to handle expiration time of the temporary credentials. More info can be found at https://developer.admiralcloud.com/knowledgebase/uploading-to-admiralcloud/
Now use the response to upload your media to the given destination. Make sure to call S3.success after every uploaded item and finally, after you have uploaded all items, call S3.uploadComplete.
Optionally you can also send dropsite.uploadStarted. This will inform the recipient about the upload and the approx time for the upload.
In order to give visual feedback to logged in users (waiting for your upload), you might want to create and update activities (see Activity Controller).
Please remember – as soon as you make the S3.uploadComplete call, your token is invalidated and you can no longer sends data to our API. Please note that it is important to send this S3.uploadComplete call – otherwise the uploaded media items will be marked as “unsuccessful upload” and be automatically deleted.
Example
Fetch the dropsite
curl --location --request GET 'https://api.admiralcloud.com/v5/dropsite/deliver/abc123'
// RESPONSE
{
"link": "fAKCgk5CCp3NsRroc6BrcG",
"clientId": "822e8ccd-0bee-4592-a53f-1b22ab04eded"
"code": "7a9bf4ba17734c64eba6"
}Exchange the code for a token
Send the received code and your name and email. If you do not need to fetch tags or metadata suggestions and you already have a userId, you can omit this step.
curl --location --request POST 'https://api.admiralcloud.com/v5/dropsite/abc123/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"code": "7a9bf4ba17734c64eba6",
"email": "doe@company.com,
"firstname": "Jane",
"lastname": "Doe"
}'Create upload document
Create the upload document. CreatorId and email are optional – if they are set, the newly upload mediacontainer will be created with this userId as creatorId, otherwise the creatorId of the mediacontainer equals the creatorId of the dropsite.
curl --location --request POST 'http://api.admiralcloud.com/v5/dropsite/createUpload' \
--header 'Content-Type: application/json' \
--data-raw '{
"link": "abc123",
"waitForCompletion": true,
"payload": [{
"type": "image",
"fileName": "file1",
"originalFileExtension": "jpg",
"fileSize": 100,
"metadata": [
{
"title": "container_name",
"content": "My uploaded image 1",
"language": "uni"
}
]
}],
"creatorId": 1234567,
"email": "doe@company.com"
}'
// RESPONSE
{
"uploadId": "587acf71-20b3-43aa-9fe3-0d792236ee00",
"processed": [
{
"id": 12345678,
"bucket": "s3-bucket-for-upload",
"region": "eu-central-1",
"s3Key": "s3-key-for-upload",
"credentials": {
"AccessKeyId": "ABC",
"SecretAccessKey": "secret-for-upload",
"SessionToken": "session token",
"Expiration": "2021-07-04T09:15:14.000Z"
}
}
],
"error": [],
"transferAcceleration": false
}Start uploading
Now start uploading to region, bucket and s3Key using the provided credentials. If your upload for the file is done, call S3.success. If all files are uploaded call S3.uploadComplete.