Upload a file
To upload a file you access the /apiv2/uploadservice/upload
endpoint and supply the file contents in a HTTP POST
request. Each request is limited to maximum 4Mb of data so if the file to be uploaded is larger it need to be posted in multiple requests. (There is no minimum upload file so segments can be less in size if need be.)
First upload request
When the first request is issued, it responds with an uploadFileId. The uploadFileId is used in the following upload requests and when storing the uploaded file in ImageVault. Use application/octet-stream as content type for upload requests and post the file contents as binary data.
Following upload requests
If file needs to be uploaded in multiple requests the uploadFileId is used in the url of the following posts on the format /apiv2/uploadservice/upload/uploadFileId
. Each following request will be appended to the uploaded file
Storing the file in ImageVault
After all parts of the file has been uploaded, call the /apiv2/mediacontentservice/storecontentinvault
and supply the filename, content type, uploadFileId and the id of the Vault that it should be placed in. Observe that the user uploading the image needs to have atleast Contribute access to the vault in question.
Read more about the StoreContentInVault method in the API reference.
Mark media as ready to use
Now the item is stored in ImageVault but not yet visible to the users. It is in an “Unorganized mode” that indicates that it has not yet been processed by an user (the organize view).
You can use this step to either set own metadata or add some user interaction or do nothing at all.
When done, mark the item as ready to use by calling the /apiv2/mediaservice/save
method and supply the saveOption MarkAsOrganized.
Note
You can store metadata and categories in the same Save call. Just supply them in the mediaItem and bitwize add those flags to the saveOption.
Read more about the Save method in the API reference.
Example
The example will upload a text file with two lines wich each line in different upload requests. Authentication has already been performed and we have an existing authorization token.
First upload request
This will initiate the upload and upload the first part of the file.
POST http://imagevaultui.local/apiv2/uploadservice/upload HTTP/1.1
Authorization: Bearer mi3hxynuho7s0j8sf8a0
X-Requested-With: XMLHttpRequest
Content-Type: application/octet-stream
Host: imagevaultui.local
Content-Length: 30
Expect: 100-continue
This is the first row of data
First upload response
The response will contain an upload id that should be used in the following upload sessions
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 22
"eSb9GNFURwVgKuJMpsmf"
Second upload request
The upload id is appended to the url of the upload service to indicate that the supplied data should appended to the first uploaded segment
POST http://imagevaultui.local/apiv2/uploadservice/upload/eSb9GNFURwVgKuJMpsmf HTTP/1.1
Authorization: Bearer mi3hxynuho7s0j8sf8a0
X-Requested-With: XMLHttpRequest
Content-Type: application/octet-stream
Host: imagevaultui.local
Content-Length: 31
Expect: 100-continue
This is the second row of data
Second upload response
The response will return the same upload id as an indication that it has appended the data
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 22
"eSb9GNFURwVgKuJMpsmf"
Store content in vault request
This request stores the uploaded media in vault 3.
POST http://imagevaultui.local/apiv2/mediacontentservice/storecontentinvault HTTP/1.1
Authorization: Bearer mi3hxynuho7s0j8sf8a0
X-Requested-With: XMLHttpRequest
Content-Type: application/json
Host: imagevaultui.local
Content-Length: 100
Expect: 100-continue
{"uploadFileId":"eSb9GNFURwVgKuJMpsmf","filename":"test.txt","contentType":"text/plain","vaultId":3}
Store content in vault response
Here you will get the details of the media item that was stored. The most important part is the Id of the media item.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 136
{
"Id": 27216,
"VaultId": 3,
"Name": "test.txt",
"DateAdded": "2016-06-25T10:34:36.0605078+02:00",
"AddedBy": "iv4sdk"
}
Save media request
To mark the media as ready to use, we call the save method and supply the Id of the media item and the saveOption 4 (MarkAsOrganized) that will indicate that the media item is ready to use.
POST http://imagevaultui.local/apiv2/mediaservice/save HTTP/1.1
Authorization: Bearer mi3hxynuho7s0j8sf8a0
X-Requested-With: XMLHttpRequest
Content-Type: application/json
Host: imagevaultui.local
Content-Length: 45
Expect: 100-continue
{"mediaItems":[{"Id":27216}],"saveOptions":4}
This will complete the upload/organize phase and make the uploaded item available to all users with access to the vault where the item is uploaded in.