VIDIZMO REST API Reference Guide

Introduction

VIDIZMO’s powerful API integration allows customer organizations to access and use our application resources to build up their own platforms. With capabilities to fully enable VIDIZMO features similar to our web portal, our APIs allow complete management of your portal’s users, content, access rights, comments, reporting, and much more.

This guide shall walk you through:

• Understanding VIDIZMO resources and what they have to offer using REST APIs
• Getting started with using VIDIZMO APIs 

If you want to view some examples of how to send/receive an HTTP Request based on your business use-case using VIDIZMO REST Services, see:

• Using REST APIs - integrating video analytics within CRM for marketing campaigns
• Using REST APIs - integrating recorded lecture sessions on your own LMS Portal 

Understanding VIDIZMO Basics

Before you proceed with using REST APIs, it is important for you to understand a few VIDIZMO-specific terms and their use-cases:

Tenant Context

VIDIZMO is a multi-tenant application where each user, media or action is associated with the tenant it belongs to. Tenant is used to describe the autonomy of a single VIDIZMO Portal and the operations, access controls and configurations that lie within. While this holds true, we have two types of tenants in VIDIZMO:

• Account
• Portal

While they remain autonomous in user and content segregation, there are certain settings and configurations that a Portal's Manager may choose to inherit from the parent Account - such as site branding, menu items, banners, tags.

When an organization uses VIDIZMO for a single tenant, its type remains Account. Yet, Portals allow organizations to create child tenants of the main tenant and inherit some of the generic organizational settings forward.

Now, using VIDIZMO REST APIs, you can carry out multiple changes to the tenant in various areas such as:

• General Settings - these enable you to change Portal's Title, Description, which features have been enabled, purge policy, etc.
• Branding Settings - these enable you to change Portal's branding such as styling, banners, logos, etc.
• Apps Configuration - these help you configure settings for various apps integrated within your portal
• Thesaurus - helps you replace portal-specific terms to suit your own organizational jargon
• Anonymous Users Policy - helps you configure the level to which an anonymous user may interact with the content in your portal

These are just some of the settings you may configure, more details about can be found in the REST API Reference - TenantInfo.

User Context

Every user in VIDIZMO has certain set of permissions that allow them to configure various administrative policies in the portal, and have access to as well as interact with the content of the portal.

These sets of permissions are determined by the role assigned to a user. Following are the roles from highest to lowest level:

1. Administrator
2. Managers
3. Moderators
4. Contributors
5. Viewers
6. Anonymous

After your organization successfully signs up for a VIDIZMO portal, the user who created the account is granted the role of an “administrator” automatically. 

VIDIZMO provides each user role certain permissions to perform actions. User role of an administrator is allowed to access all resources and perform all update actions that encompass VIDIZMO API.

Now, for carrying out any action in a tenant using REST APIs, you need an authentication token (more about which is covered in a separate section later). This token shall contain information about the user who is trying to use REST APIs to fetch/update Portal's resources - based on which the system shall decide whether they are authorized to perform the action. If the user has permission to perform the action, the HTTP request shall return with a 200, otherwise it shall return an exception for Unauthorized Access.

Say for example if you wish to feature a particular media on the Account homepage, you will be required to make an HTTP PUT Request to /api/v1/mashup using authentication token of a user whose role is Moderator or higher in the Portal.

Mashups

Mashup refers to all types of media in VIDIZMO Portal, it includes:

• Video
• Audio
• Image
• Document
• Collection
• Playlist
• Quiz
• Survey
• Live

Regardless of how one media type is seemingly quite different from the other, their structure is quite the same and Mashup resource includes properties to accommodate access-control settings, as well as metadata information of every media.

Say for example if you wish to add a new question to a Quiz or you wish to update title of your video, you will be required to make an HTTP PUT Request to /api/v1/mashup including the relevant mashupPart. For Quiz, it shall be Content, where as for video, it shall be BasicInfo.

For a more detailed information about the various parts of a mashup and what each of them entails, see: API Reference - Mashup.

Using VIDIZMO APIs

VIDIZMO APIs are based on REST architecture which can be accessed via HTTP requests. Representational State Transfer (REST) APIs are service endpoints that support sets of HTTP operations (methods), which provide create, retrieve, update, or delete access to the service's resources.

Before you start

• We recommend you go through the structure of a REST API Request and Response before you get started.
• As mentioned in the above article, any app that wishes to utilize VIDIZMO APIs for integration shall route requests to the following base URL where domain is your VIDIZMO Portal's URL: {domain}/api/v1/. The complete Request URL will be dependent on the request endpoint for the resource you are trying to access. For example, you can get analytics against a media via a GET request to this URL: https://{{domain}}/api/v1/analytics/search.
• Detailed documentation of various APIs available in VIDIZMO can be found here: VIDIZMO API Documentation.

If any organization wants to test their integration with VIDIZMO APIs, VIDIZMO also provides a pre-configured sandbox environment. For more information about setting up sandbox environment, contact VIDIZMO support. 

Authentication

All VIDIZMO APIs are divided into two categories:  

1. APIs where authentication is a requirement

These consists of all the VIDIZMO APIs that perform administrative actions on portal like adding users, deleting users etc. On these APIs all HTTP calls need to be authenticated first. Then action is performed based on authorization as per user context. 

2. APIs where authentication is optional 

These consists of all the VIDIZMO APIs on which HTTP requests may not need to be authenticated. This is in case of non-administrative requests like getting information on mashups which have been set to allow anonymous access.

When making an HTTP Request to access VIDIZMO resources:

1. If bearer token is not passed in HTTP request headers, then the requests won’t be authenticated and the call will be executed in context of an anonymous user.
2. If bearer token is passed in HTTP request headers, then the request will be authenticated. If authentication is successful, then action will be performed based on authorization accordingly to the user profile against whom the token has been generated.

Note: Public/Anonymous Access is not available in VIDIZMO Digital Evidence Management (DEMS) product package.

VIDIZMO APIs use a bearer authentication scheme to authenticate HTTP requests. This means that if an app wishes to use an API which requires to be authenticated, then the app should pass a unique token called a bearer token in the header of the HTTP request 

An app can use {{domain}}/api/v1/user/authenticate API to obtain a bearer token. Once obtained, this token can be used to perform multiple actions in the Portal using REST API based on the permissions that a user holds. This token is subject to expiry when user logs out, or after the token expires, in which case you will have to refresh access token by sending the previous access token.

Here is an illustration of the process. To read more about it, see: how to send an authentication request to acquire access token.

https://{domain}/api/v1/tag/search?Keyword=background&TagParts=BasicInfo

200

{
    "tags": [
        {
            "id": 31858,
            "name": "background"
        }
    ],
    "resultCount": 1
}

https://{domain}/api/v1/user/esther.fray%40gmail.com?userPartsToFetch=BasicInfo 

400

{
    "name": "UnAuthorizedException",
    "incidentId": "99009ed8-dc31-4c5c-a883-923341784068",
    "exceptionDetails": []
}

500