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:


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:


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.




Pagination

When an app wants to use VIDIZMO APIs to fetch relevant data, they get 10 records returned by default. If an app has a specific use-case which needs more data to be returned, then in order to cater to that, VIDIZMO APIs give the app an option to request more records. An example for this could be when requesting to search user via {{domain}}/api/v1/user/search API. When using this VIDIZMO API, it asks for two additional query parameters:

  1. PageIndex (Specifies the start index of the record)
  2. PageSize (Specifies the total number of records required)


Error Codes

For apps to know the status of their requests, VIDIZMO APIs return HTTP status codes as responses. This enables the app’s developers to have a clear understanding of the system and debug problems easily, if any.

VIDIZMO APIs have the following status code responses:


CodeResponseDescription
200SuccessWhen an API call successful fetches or posts the data on the server
400Bad RequestThis indicates an error has been made  by the user while executing the API call
500Server ErrorWhen the call has successfully executed but Server returns an exception due to some internal issue


Example for Code 200
Below is an example of an API request to obtain basic information of tags based on search criteria:


Request Method: GET


Request URL: /api/v1/tag/search


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

Response Status Code:

200

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


Example for Code 400
Below is an example of an API request to obtain basic information of user on the basis of their email. User is not authorized to use this API.


Request Method:  GET


Request URL: /api/v1/user/{emailaddress} 


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


Response Status Code:

400

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


Example for Code 500

Below is an example of an API request which returns a response code for a server error, where Response body is empty:

Response Status Code:

500


Rate limits

Rate limits in VIDIZMO APIs are defined by the maximum number of requests that can be made on a VIDZMO API by a single IP Address. 

Any app that requests to VIDIZMO APIs have a rate limit of 10 requests per second.


Following articles would help you understand VIDIZMO API integrations better: