TABLE OF CONTENTS

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. Businesses may implement functionalities that can best cater to their use-case scenarios. 


Getting started with VIDIZMO APIs  

VIDIZMO APIs are based on REST architecture which can be accessed via HTTP requests.  


The documentation to all of VIDIZMO APIs can be found here: VIDIZMO API Documentation. 

 

To get started, any app that wishes to utilize VIDIZMO APIs for integration shall route requests to the following base URL: {{your-domain}}/api/v1/doc/index.html The complete URL will be dependent on the request endpoint. Using this base URL+ endpoint, apps can easily access all VIDIZMO APIs.  

 

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 a HTTP calls may not need to be authenticated.  This is in case of non-administrative requests like access to mashups.


There are two cases of authentication here:

  1. If bearer token is not passed in HTTP request headers, then the requests won’t be authenticated and action will be performed in the 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 user context.

Some VIDIZMO APIs require the requests they receive to be authenticated. VIDIZMO APIs use a bearer authentication scheme to authenticate HTTP requests. This means that if an app wishes to use an API which require 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 {{your-domain}}/api/v1/user/authenticate API to obtain a bearer token. Following is an example of how a bearer token can be obtained as well as the flow diagram: 

 

Request: HTTP POST
Request API: /api/v1/user/authenticate 

{{your-domain}}/api/v1/user/authenticate 

Response status code:

200
Request body: 
{ 
"emailAddress":"john.doe@gmail.com",
"password": "examplepassword",
"tenantId": "1234"
}

Response body:

"N2UCSNDDGI4NND5NMBZLV7ZBV2I3BZLUWQFXF6MGZKXTOCLHPH2SLPR2TMPM54M7CTG4DLFNE5KHSZ4LARTLQVRRCCRFAGVAG242M5RB3S5D4TEXKTSH4AHNMLTB3IF5IZYI4XSHRDDF2YFPLYAEMQL3Y3BKGZHCSDC2T2DQY64RC5Q3R5CQ" 



Once a bearer token is obtained, then they can be passed in the header of the HTTP request to the VIDIZMO API for requesting further information.


Following is an example of an API request made using a bearer token in header as well as a flow diagram. In this example we are fetching basic information of a user on the basis of their email address.

 

Request: HTTP GET
Request API:  /api/v1/user/{emailAddress} 

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

Response status code: 

200

Request header: 

your-bearer-token

Response body:

{  
"firstName": "John",
"lastName": "Doe",
"emailAddress": john.doe@gmail.com,
"addedById": 575951,
"addedDateTime": "2020-06-02T06:35:10.99",
"updatedDateTime": "2020-06-19T13:23:47.58",
"lastLogOn": "2020-06-29T12:46:08.157",
"id": 575952,
"defaultTenantId": 6820,
"confirmationDateTime": "2020-06-02T06:35:58.21"
}




A bearer token that has been generated can expire in two cases:

  1. When a user logs out via {{your-domain}}/api/v1/user/logout API.
  2. When a user is automatically logged out after few minutes of inactivity (The default time for login timeout is 20 minutes which can be changed as well)

 

VIDIZMO APIs will not be able to perform the action that is requested when a token has expired. 


Following is an example of a scenario when a bearer token has expired: 

 

Request: HTTP GET 

Request API:  /api/v1/user/{emailAddress} 

{{your-domain}}/api/v1/user/authenticate/api/v1/user/esther.fray%40gmail.com?userPartsToFetch=BasicInfo 

Response status code

400

Request header: 

your-bearer-token

Request body:  

{ 
"name": "ExpiredAccessTokenException",
"incidentId": "332d7070-78b3-4730-b76f-7a5adafeab31",
"exceptionDetails": []
}


If an invalid token is passed in the header then response is as follows:

Response body: 

{ 
"name": "InvalidAccessTokenException",
"incidentId": "167c0274-515e-4f16-a309-449c9573e9c6",
"exceptionDetails": []
}


Once a token expires, a user will then have to obtain bearer token again via {{your-domain}}/api/v1/user/authenticate API. 


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 {{your-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: HTTP GET 

Request API: /api/v1/tag/search 

{{your-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: HTTP GET 

Request API:  

{{your-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.


Understanding User Context in VIDIZMO API

Every app that wants to integrate with VIDIZMO APIs needs to understand user context under which VIDIZMO APIs operate.

VIDIZMO operates under different levels of roles. 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 authorization to perform actions. User role of an administrator is allowed to access all resources and perform user-based actions that encompass VIDIZMO API.

If you use VIDIZMO APIs with a user role of Manager, then you are authorized to use VIDIZMO APIs to manage media, add and update users and groups, view analytics etc.
If you use VIDIZMO APIs with a user role of Moderator, then you are authorized to use VIDIZMO APIs related to media management only.

To learn more about user roles read: Understanding User Roles.

Each request is checked to see whether the application end-user has the necessary authorizations to perform the request, after authentication (wherever applicable). As mentioned in the authentication section, if any application end-user sends a request without a bearer token in its header, then VIDIZMO APIs (wherever authentication is not required) will attempt to execute that request as anonymous.


Following articles would help you understand VIDIZMO options better: