Uploading Assets


Asset creation is accomplished by following a workflow that consists of six distinct steps (three of which are mandatory) that will allow a user to upload, then subsequently categorize and annotate a new asset. Depending on permissions, the user may need to submit the assets for approval.

Available Upload End-Points


End-Point Description Verbs
/uploads Creates a new upload entity. POST
/uploads/:id Manipulates the entire upload record specified by :id PUT
/uploads/:id Manipulates the specific field in the upload specified by :id PATCH
/uploads/:id Cancel the upload and remove all data and files. DELETE
/uploads/:id/categories Add the uploading asset to the specified categories. POST
/uploads/:id/categories Remove the uploading asset from the specified categories. DELETE
/uploads/:id/keywords Add the specified keywords to the uploading asset. POST
/uploads/:id/keywords Remove the specified keywords from the uploading asset. DELETE
/uploads/:id/attributes Add the specified attributes to the uploading asset. POST
/uploads/:id/lightboxes Add the specified lightbox to the uploading asset POST
/uploads/:id/lightboxesassets Add an asset to the specified lightbox. POST
/uploads/:id/lightboxes/:id Manipulates the specific field in the lightbox for upload specified by :id PATCH

Step 1 - Upload (/uploads)


POST * Required

The initial POST to /uploads will create an asset record with a status of "Uploading". This will create a holder record the user can work against for the upload. The values of the record can be sent, but they are not required as they will be overwritten in the PUT request after the file is uploaded.

Data will not be verified in this POST, but will be done in the final PATCH end-point. This is because uploading an asset is a 4 step process.

1. POST to the upload resource. This creates a holding record and creates the Shared Access Signature (SAS) URL for the user to upload the file to. The SAS url allows temporary write access to BLOB storage.

2. Upload the file using the SAS URL.

3. PUT the upload to the Assets resource.

4. PATCH the upload. This step will check to see if the file needs to be renamed, and trigger any events needed by the back-end. It will also run data verification on the asset.

Note: The ID is system generated and will be ignored if set in the POST request.

Request

{
    "filename": "MyImage.jpg"
}

Response

The response from the POST consists of the Asset Identifier, the temporary file name, and the upload url.

  • id is the Guid identifier of the asset.
  • uploadUrl is the Azure Secured Asset Signature (SAS) URL where the file should be uploaded to.
  • uploadFilename is a temporary filename given to the file for security purposes. It will be changed back to the original filename after upload is complete.

{
    "id":"2c6b34da-c2fd-41ea-84ee-3ab32219b591",
    "uploadUrl":"[Shared Access Signature URL]",
    "uploadFilename":"2c6b34da-c2fd-41ea-84ee-3ab32219b591.bin"
}

Upload File


This step requires the user to upload the file to blob storage in Azure using the SAS URL provided in the POST step. The upload is accomplished by issuing a PUT, or a number of PUT request to the SAS URL with the binary segments of the file as the body. It is important to note, the SAS URL expires after 24 hours and another will have to be requested at that point.

There are a few key points to this upload.

  • Maximum file size Azure supports is 200GB.
  • If the file is over 64 MB, it must be broken up into segments. The maximum segment size is 64 MB, but MediaValet recommends using much smaller segments.

Step 2 - Add/Remove Categories (/uploads/:id/categories)


The second step forces the user to apply at least one category to each asset being uploaded. POST/DELETE end-points are available to add/remove the categories to/from the asset.

POST * Required

POST adds one or more categories to the upload. The categories are added by supplying a list of category IDs in the body of the request.

Request

[
    /* List of Category IDs to add the upload to. */
    "82d57c66-6da6-4f31-a7c3-eca0ea09a86a",
    "07faa086-fcbe-46f9-b2f8-04782cd43438"
]

Response

"Payload":
[
    /* List of Category IDs to which upload is recently added. */
    "82d57c66-6da6-4f31-a7c3-eca0ea09a86a",
    "07faa086-fcbe-46f9-b2f8-04782cd43438"
]

DELETE

DELETE removes one or more categories from the upload. The categories can be removed by supplying a list of category IDs in the body of the request.

Request

[
    /* List of Category IDs to remove from upload. */
    "82d57c66-6da6-4f31-a7c3-eca0ea09a86a",
    "07faa086-fcbe-46f9-b2f8-04782cd43438"
]

Response

"Payload":
[
    /* List of Category IDs to which upload is recently removed. */
    "82d57c66-6da6-4f31-a7c3-eca0ea09a86a",
    "07faa086-fcbe-46f9-b2f8-04782cd43438"
]

Step 3 - Add/Remove Keywords (/uploads/:id/keywords)


The third step allows the user to (optionally) add/remove one or more keywords to each asset being uploaded. To add or remove keywords POST/DELETE end-points are available.

POST

POST adds one or more keywords to the upload. They are added by supplying a list in the body of the request.

Request

[
    /* List of keywords to add the upload to. */
    "keyword1","keyword2"
]

Response

"Payload":
[
    /* List of all keywords that apply to this upload. */
    "keyword1","keyword2"
]

DELETE

DELETE removes one or more keywords from the upload. They are removed by supplying a list in the body of the request.

Request

[
    /* List of keywords to remove from upload */
    "keyword1","keyword2"
]

Response

"Payload":
[
    /* List of all keywords to which upload is recently removed.*/
    "keyword1","keyword2"
]

Step 4 - Add Attributes (/uploads/: id/attributes)


The fourth step allows the user to (optionally) add values for one or more custom attributes, for each asset being uploaded. To add attribute values, attribute POST end-point is available.

POST

POST adds one or more attributes to the upload. They are added by supplying a list in the body of the request. Set the values as specified in the key/value list in the body, where the key is the id of the attribute, and the value is the value to set.

Request

[
    /* List of attributes to add the upload to. */
    {"39740c22-e134-4ccf-b9c2-879ae773ef52":"2016-08-31T18:30:00.000Z"},
    {"18a182e2-c581-479c-a868-a461d65b84d4":"2016-09-21T18:30:00.000Z"}
]

Response

"Payload":
{
    "attributes": {
        "39740c22-e134-4ccf-b9c2-879ae773ef52": "8/31/2016 6:30:00 PM",
        "18a182e2-c581-479c-a868-a461d65b84d4": "9/21/2016 6:30:00 PM"
    }
}

Step 5 - Add Title/Description/FileSize (/uploads/: id)


The fifth step allows the user to (optionally) supply a description to each asset being uploaded as well as change the default title. By default the system will use the filename (without file extension) as the asset title.

Note: It is important to supply the original file size in this step. In order to supply a title, description and fileSizeinBytes upload the PUT end-point is available.

PUT

The PUT request (/uploads/:id) is used to update the entire upload record. It is important to note that the original file size must be included in the model in the request. This file size is used to ensure the file has been completely uploaded to blob storage. The record in storage will be completely overwritten by the values in the put request. If the file has been completely uploaded, the details supplied in the PUT request overwrite the existing record. Please be careful with this.

Request

{
    "filename": "MyImage.jpg"
    "title": "First Asset.",,
    "description": "This is my first asset.",
    "status": 0,
    "fileSizeInBytes": [Size in bytes]
}

The response from the PUT consists of the title, description, filename and fileSizeInBytes.

Response

"Payload":
{
    "title": " First Asset.",
    "description": "This is my first asset.",
    "filename": "MyImage.jpg",
    "status": 0,
    "fileSizeInBytes": [Size in bytes]
}

Step 6 - Finalize Upload (/uploads/: id)


The sixth and final step is mainly a confirmation that the assets were successfully uploaded. After this, the system needs to render thumbnails and otherwise process the assets. This may take some time depending on overall load of the system and how many assets were added. In order to finalize the upload, the PATCH end-point is available.

PATCH * Required

The PATCH request finalizes the upload. PATCH indicates that the upload is ready for processing with the ReadyForProcessing status update. Before it starts processing, the finalize upload patch end-point applies the pre-flight check which validates the following parameters:

  1. If the file size in Blob storage does not match the file size submitted, a 404(Not Found - Upload of [SAS] failed) is returned as the status of the request.
  2. If file name has invalid characters, a 400(Bad Request) is returned as the status of the request.
  3. At least one category must be assigned to the Asset, otherwise a 400(Bad Request) is returned as the status of the request.
  4. All required attributes should match, otherwise a 400(Bad Request) is returned as the status of the request.

The PATCH request sends instructions on updating single fields. There can be more than one instruction per request, but each instruction should do something to a single field.

PATCH will not work if the asset is in the Uploading state.

The fields that are accepted for PATCH are:

  • Title
  • Description
  • FileSizeInBytes
  • Filename
  • Status (ReadyForProcessing)

Request

[
    {"op":"replace","path":"/status","value":1}
]

Response

PATCH end-point offers both Synchronous and Asynchronous operation therefore the response are different in both cases because asynchronous operation request is processed by other services (web-jobs).

Synchronous Response (/uploads/id?runAsync=false)

{
    "id": "4ac3cd6c-e1ce-4dba-ae78-56b0a2f26bd9",
    "title": "TITLE OF ASSET",
    "description": "This is my first asset.",
    "status": " /* Status Value */ ",
    "rating": {
        "avg": 3,
        "user": 4
    },
    "file":{
        "localName": "MyImage",
        "name": "MyImage_C0DCB3E4-F972-4B93-BEA4-5707CE035338",
        "ext": "jpg",
        "mimeType": "image/jpg",
        "sizeInBytes": 850000,
        "colorMode": "RGB",
        "resolution": "300 dpi",
        "width": 700,
        "height": 466,
        "units": "px",
    },
    "attributes":{
        "attribute1": {
            "id": "b0381d03-386d-46c5-b5ef-9701d8e98aec",
            "value": "valueAsString",
            "type": "[string | number | date | lookup ]",
            "lookupValues": [ /* List of string values /* ], // include if type == lookup
            "_functions":{
            }
        },
        // ...
    },
    "media": {
        "type": " /* Media Type */ ",
        "basePath":"http://mediavaletteststorage.blob.core.windows.net/medialibrary-02-053e0555-acc5-45b9-823b-e32e8a8516df",
        "thumb": "-r/1/MyImage.jpg",
        "full": "-r/4/MyImage.jpg",
        "original": "/MyImage.jpg"
     },
    "record":{
        "createdAt": "2013-10-16T21:18:28Z",
        "createdBy": {
            "id": "A42D6EB8-09D5-47A3-A0CD-4FB52A13AF11",
            "username": "someone@ourassets.com"
        },
        "modifiedAt":"2014-02-14T10:59:29Z",
        "modifiedBy": {
            "id": "A42D6EB8-09D5-47A3-A0CD-4FB52A13AF11",
            "username": "someone@ourassets.com"
        },
        "version": {
            "version": "5218355",
            "current": "4ac3cd6c-e1ce-4dba-ae78-56b0a2f26bd9",
            "head": "4ac3cd6c-e1ce-4dba-ae78-56b0a2f26bd9",
            "parentId": "00000000-0000-0000-0000-000000000000",
            "isVersionable": true,
            "isLatestVersion": true,
            "isMajorVersion": true
        }
    },
    "categories": [ /* List of categories */ ],
    "keywords": [ /* List of keywords */ ],
    "relatedAssets": [ /* List of related assets */ ]
}

Asynchronous Response (/uploads/id?runAsync=true)

"Payload":
{
    "batchId": "e0059283-1fec-4fd6-a512-23aba14b5eba"
}

Here the BatchId is a unique identifier for the web-job which processed the assets.

Submitting the assets for approval


The above 6 steps are sufficient if the user has permission to upload new assets. For some users, new assets must first be approved and the approval process starts in the upload section. If user does not have permission to approve an asset then the user may be forced through a process of submitting the assets for approval. In order to send assets for approval 3 separate steps and end-points are available.

Step 1 - Create New Lightbox for Assets (/uploads/:id/lightboxes)


POST

POST creates a new lightbox for an upload. The lightbox is added by supplying the lightbox details in the body of the request.

Request

{
    name: "Name of Lightbox",
    description: "Long description of the lightbox"
}

Response

{
    id: "7FCE8D62-8894-4FD8-A696-1F0DB6AB8395",
    name: "Name of Lightbox",
    description: "Long description of the lightbox",
    assetCount: 23,
    owner: {
        id: "CD30D8B1-31FD-46F0-B637-13E262F27C9D",
        username: "someone@lightbox.com"
    },
    approver: {
        id: "A42D6EB8-09D5-47A3-A0CD-4FB52A13AF11",
        username: "admin@lightbox.com"
    },
    record: {
        createdAt: "2013-10-16T21:18:28Z",
        createdBy: {
            id: "A42D6EB8-09D5-47A3-A0CD-4FB52A13AF11",
            username: "someone@ourassets.com"
        },
        modifiedAt: "2014-02-14T10:59:29Z",
        modifiedBy: {
            id: "A42D6EB8-09D5-47A3-A0CD-4FB52A13AF11",
            username: "someone@ourassets.com"
        }
    }
}

Note: This step is optional if the user already has a lightbox.

Step 2 - Add Assets to Lightbox (/uploads/:id/ lightboxesassets)

POST

POST adds a lightbox to the upload. The lightbox is added by supplying the lightbox id in the body of the request.

Request

{
    /* Lightbox id */
    "cd08c35b-b184-4d5f-9639-6a81306ce55b"
}

Response

"Payload":
{
    /* Lightbox id */
    "id": "cd08c35b-b184-4d5f-9639-6a81306ce55b"
}

Step 3 - Send Lightbox to Approver User (/uploads/:id/lightboxes/:id)

PATCH

PATCH request sends a lightbox which contains assets to the approver user for assets approval. The lightbox is added by supplying the lightbox id in the body of the request.

PATCH sends instructions on updating single field's. It manipulates the specific field in the lightbox for upload specified by: id.

The fields that are accepted for the PATCH are:

  • Approver ID

Request

[{
    /* Approver id */
    "cd08c35b-b184-4d5f-9639-6a81306ce55b"
    "path": "/approverId",
    "value": "76ccd378-7146-4613-a9c3-8d1af652c83e"
}]

Response

"Payload":
{
    /* Approver id */
    "76ccd378-7146-4613-a9c3-8d1af652c83e"
}