In this post, we’ll go through all Media Vault endpoints and learn how to use them in practice. Don’t forget that Media Vault, in general, is a module created for application administrators as the central control point for creating and managing files, so it means you need to be logged in to perform all of the following operations. Once you log in, you app will get an access token allowing it to perform certain actions, such as creating, updating and deleting files.

Creating new files (Media Vault Stream POST)

In the previous blog post, we said that Media Vault Stream creates the file itself, and based on that Media Vault automatically creates an entry which holds all the information on that file. That’s why there’s no POST method in Media Vault - you can’t create information about the file that doesn’t exist (isn’t created in the Media Vault Stream).

curl
-X POST
-H "Authorization: bearer <access-token>"
-H "Content-Type: multipart/form-data"
-F "File=@[object Object]" "https://api.baasic.com/<version>/<api-key>/media-vault-streams/videos/<video-name.mp4>"

If the file is successfully uploaded (in our case, video1.mp4), you should get a response code 201 (Created) with the following object:

{
    "description": "",
    "fileExtension": ".mp4",
    "fileName": "video1",
    "fileSize": 4010000,
    "height": null,
    "derivedEntries": [],
    "metaData": null,
    "ownerUser": null,
    "ownerUserId": "bQtZG36zG23DQDC8098990",
    "path": "/videos/video1.mp4",
    "width": null,
    "dateCreated": "2016-05-31T12:13:03.806064",
    "dateUpdated": "2016-05-31T12:13:03.806064",
    "id": "ecKggkHkhqgvPwON0GHLb0"
}

Retrieving files (Media Vault Stream GET)

If you perform a GET request for a file on a Media Vault Stream like this:

curl
-X GET
-H "Authorization: bearer yaccess-token"
"https://api.baasic.com/<version>/<api-key>/media-vault-streams/<file-id>"

you will get 200 OK HTTP response code, along with the requested file stream - and if you want to retrieve the information about the file, use Media Vault GET.

The GET method can be used with a file name, as well as with a file ID.

Updating files (Media Vault Stream PUT)

Since working with Media Vault Stream means you’re working with the underlying file, and not the information about it, updating the file means replacing it with another one. Note that the formats of both files, replaced and the new one, don’t have to be the same.

curl
-X PUT
-H "Authorization: bearer <access-token>"
-H "Content-Type: multipart/form-data"
-F "File=@[object Object]" "https://api.baasic.com/<version>/<api-key>/media-vault-streams/videos/<video-name.mp4>"

We have replaced video1.mp4 with another file, and as a response, you should just get the code 204 (the server successfully processed the request, but is not returning any content).

So far we’ve seen how to manage files (resources); how to create, retrieve and update them - all through Media Vault Stream endpoints.


Now let’s see how to work with file information through Media Vault REST API endpoints.

Retrieving information about a file (Media Vault GET)

To retrieve information on a certain file, add the file ID to the GET request on the Media Vault endpoint:

curl
-X GET
-H "Authorization: bearer <access-token>"
"https://api.baasic.com/<version>/<api-key>/media-vaults/<file-id>"

Result:

{
    "description": "",
    "fileExtension": ".mp4",
    "fileName": "video1",
    "fileSize": 4010000,
    "height": null,
    "derivedEntries": [],
    "metaData": null,
    "ownerUser": null,
    "ownerUserId": "bQtZG36zG23DQDC8098990",
    "path": "/videos/video1.mp4",
    "width": null,
    "dateCreated": "2016-05-31T12:13:03.806064",
    "dateUpdated": "2016-05-31T12:13:03.806064",
    "id": "ecKggkHkhqgvPwON0GHLb0"
}

Media Vault Search (GET by search criteria)

Mobile and web applications can have thousands of files, that’s where GET by search comes in handy. It’s used to retrieve a (filtered|sorted|paged) collection of media vault resources that match the specified criteria. To see parameters used for this request, click here.

Following request will retrieve all files containing ‘text’, and the result will show first page of the result set, 5 results per page, sorted by date updated (descending).

curl
-X GET
-H "Authorization: bearer <access-token>"
"https://api.baasic.com/<version>/<api-key>/media-vaults/?searchQuery=<search-query>&page=1&rpp=5&sort=dateUpdated|desc"

Result:

{
    "embed": null,
    "item": [
        {
            "description": "",
            "fileExtension": ".mp4",
            "fileName": "video1",
            "fileSize": 4010000,
            "height": null,
            "derivedEntries": [],
            "metaData": null,
            "ownerUser": null,
            "ownerUserId": "bQtZG36zG23DQDC8098990",
            "path": "/videos/video1.mp4",
            "width": null,
            "dateCreated": "2016-05-31T12:13:03.806064",
            "dateUpdated": "2016-05-31T12:13:03.806064",
            "id": "ecKggkHkhqgvPwON0GHLb0"
        }
    ],
    "links": [],
    "page": 1,
    "recordsPerPage": 5,
    "searchQuery": "video",
    "sort": "dateUpdated|desc",
    "totalRecords": 1
}

Updating file information (Media Vault PUT)

This call updates the information about the file - not the file itself. If you want to update the file (replace it), use the Media Vault Stream PUT.

curl
-X PUT
-H "Content-Type: application/json"
-H "Authorization: bearer <access-token>"
-d '{
    "path":"</folder/video-name.mp4>", 
    "description":"<description>",
    "ownerUserId": "<owner-user-id>"
}'
"https://api.baasic.com/<version>/<api-key>/media-vaults/<file-id>"

Response: 204 (the server successfully processed the request, but is not returning any content).

DELETE a media vault resource

curl
-X DELETE
-H "Authorization: bearer <access-token>"
"https://api.baasic.com/<version>/<api-key>/media-vaults/<file-id>"

Response: 204 (the server successfully processed the request, but is not returning any content).

Update or delete a batch of media resources

To update a collection of Media Vault resources, use Media Vault PUT batch; and to delete a collection, use Media Vault DELETE batch method.


Now you know how to manage Media Vault streams and data; our next blog post will explain how to use endpoints for Media Vault settings and preprocessing provider settings.

Feel free to leave a comment

comments powered by Disqus