How to use MK.IO APIs - step by step

How to use MK.IO APIs - step by step

This article will describe the step by step on how to use MK.IO APIs documented here: https://docs.io.mediakind.com/reference/the-mediakind-api

  1. As you already know, you can use APIs to automate the process of different tasks, in MK.IO world they can be used to automate creation of storage accounts, migration of assets, creation of live events, etc. basically any action you take on the UI can be automated using MK.IO APIs.
  2. In this article we will describe the most common use case right now = Migration of one asset
  3. This description can be extrapolated to the usage of any documented API.

1. The first thing you will need is a token, a token will provide security when calling APIs so we do not expose anonymous access being able to call these APIs without authorization/authentication.
      To do so, first open a web browser and log into https://io.mediakind.com (sign in with Microsoft SSO), click on Sign in on the top right.
            
     Once you are logged in, open a second tab on the same browser and open this link in the new tab: https://api.io.mediakind.com/auth/token/
     This should provide you with your user_id and token. Note that this token is valid for 1 year.
            
Update: sometimes, when you open this second tab, you will see a 401 error: unauthorized.
If this happens to you, start over the process but this time open the private version (incognito in chrome and/or Inprivate in Edge) of your web browser right clicking your browser and selecting this option: 
      or           

2. Now that we have the token we will be able to use it as authorization method when calling MK.IO APIs.
    Here is an example of the asset migration API call using postman:
            
  As you can see we are using:
        a. Authorization type = API key
        b. Key = x-mkio-token
        c. Value = token field from previous url response (https://api.io.mediakind.com/auth/token/)
        d. Add to = Header

3. Now we are going to migrate an asset that is hosted in a storage account that you already have created previously in MK.IO, if you need help creating this storage account in MK.IO you can follow this other KB article: How to add storage account in MK.IO (mediakind.com)
    The API we will use to migrate 1 asset is "Create or Update Asset" documented here Create or Update Asset (mediakind.com)
    The endpoint to use for any MK.IO API will always be api.io.mediakind.com.
    This API will need some body provided as follows: {"properties":{"container":"boulder2","description":"","storageAccountName":"miosergio"}}  <<<< you will learn to find this body using the next steps in this KB
        where container is the name of the container in Azure storage and storageAccountName is your storageAccountName in MK.IO.
             
As you may have noticed, this body information is not documented in our APIs currently.

The best way to find out what is the possible body that an API will need is to do the following steps:
 1. In the browser (in MK.IO) where you will perform the action that you will do later via API, open the network tab of development tools as described in this KB: HAR file generation (mediakind.com)
 2. Once the network tab is open you can see all the activity that happens behind the scenes when you create a storage account or you migrate an asset, create live event, etc.
 3. Now with this open, perform the action, for example migrate asset (in my case the container in Azure storage is called boulder3):
      a. in this first step I clicked on Migrate asset section which opens this form that I complete:
                
      b. now I click on submit and the asset gets migrated, now I look at the network activity and click on this entry you see below that says Boulderrr with status 201 type fetch:
                      
                   

      c. the information of that entry expands (once you click on it) and I can see is the name of the API for migrate assets with method PUT (as the API documentation describes for this API)
               
      d. now click on the Payload tab and you will find what body was provided in the API call:
              
        You can use this body as a reference for the next asset or set of assets you will migrate using the APIs directly instead of the UI.