howto How to create API for mobile app or other 3rd-party frameworks

[Tech Support]

KVS can be used as a backend for any other frontend technology, such as mobile apps, rich desktop apps and etc. While KVS doesn't have API in its traditional sense, virtually any API can be created using KVS Website UI builder feature.

In this article we will provide example on creating JSON API for displaying list of videos, video player and data for any video, as well as processing signup and login actions. The very same approach can be extended to any other data supported by KVS: categorization, posts, photos and other.

It is expected that you also have some client code (typically implemented using some other technology) that can send HTTP GET / POST requests, parse JSON responses and render data in some way. This code is up to you and not explained in this article.

 

Creating API page

The idea is to create a single page that will host all blocks providing the needed data and functionality. You will need this page to set up block settings. Then you will use async method of querying and posting data to communicate with individual blocks on this page.

First, create a new page In Website UI -> Pages section of admin panel. Give it any name (e.g. API) and any external ID (e.g. api). Add 4 blocks to this page:

• list_videos block to query various lists of videos with different sorting and filtering options;
• video_view block to query data for each video;
• signup block to process signup requests and register new users;
• logon block to process login requests and authenticate existing users.

There is no need to do any code formatting here, as we are not going to display this page in a direct way:

{{insert name="getBlock" block_id="list_videos" block_name="API videos"}}
{{insert name="getBlock" block_id="video_view" block_name="API video view"}}
{{insert name="getBlock" block_id="signup" block_name="API signup"}}
{{insert name="getBlock" block_id="logon" block_name="API logon"}}

After you save this page, you will see 4 blocks appear under it where you need to configure options and their templates.

 

Displaying video list

Open API videos block for editing. In template use the following code:

{{php}}
header('Content-Type: application/json');
{{/php}}
[{{foreach name="data" item="item" from=$data}}
{
"video_id":  {{$item.video_id|default:0}},
"title": {{$item.title|json_encode}},
"description": {{$item.description|json_encode}},
"duration": {{$item.duration|default:0}},
"screen_url": {{$item.screen_url|json_encode}},
"screen_main": {{$item.screen_main|default:0}},
"screen_amount": {{$item.screen_amount|default:0}},
"video_viewed": {{$item.video_viewed|default:0}},
"rating": {{$item.rating|default:0}},
"rating_amount": {{$item.rating_amount|default:0}},
"post_date": {{$item.post_date|json_encode}},
"view_page_url": {{$item.view_page_url|json_encode}},
{{if count($item.categories)>0}}
"categories": [{{foreach name="data_categories" item="item_categories" from=$item.categories}}{"id": {{$item_categories.category_id|default:0}}, "title": {{$item_categories.title|json_encode}}, "dir": {{$item_categories.dir|json_encode}}}{{if !$smarty.foreach.data_categories.last}},{{/if}}{{/foreach}}],
{{/if}}
{{if count($item.tags)>0}}
   "tags": [{{foreach name="data_tags" item="item_tags" from=$item.tags}}{"id": {{$item_tags.tag_id|default:0}}, "title": {{$item_tags.title|json_encode}}, "dir": {{$item_tags.dir|json_encode}}}{{if !$smarty.foreach.data_tags.last}},{{/if}}{{/foreach}}],
{{/if}}
{{if count($item.models)>0}}
   "models": [{{foreach name="data_models" item="item_models" from=$item.models}}{"id": {{$item_models.model_id|default:0}}, "title": {{$item_models.title|json_encode}}, "dir": {{$item_models.dir|json_encode}}}{{if !$smarty.foreach.data_models.last}},{{/if}}{{/foreach}}],
{{/if}}
{{if count($item.content_source)>0}}
   "content_source": {"id": {{$item.content_source.content_source_id|default:0}}, "title": {{$item.content_source.title|json_encode}}, "dir": {{$item.content_source.dir|json_encode}}},
{{/if}}
{{if count($item.dvd)>0}}
   "dvd": {"id": {{$item.dvd.dvd_id|default:0}}, "title": {{$item.dvd.title|json_encode}}, "dir": {{$item.dvd.dir|json_encode}}},
{{/if}}
{{if count($item.user)>0}}
   "user": {"id": {{$item.user.user_id|default:0}}, "display_name": {{$item.user.display_name|json_encode}}},
{{/if}}
"type": "{{if $item.is_private==2}}premium{{elseif $item.is_private==1}}private{{else}}public{{/if}}",
"status": "{{if $item.status_id==0}}inactive{{elseif $item.status_id==1}}active{{elseif $item.status_id==2}}error{{elseif $item.status_id==3}}processing{{elseif $item.status_id==4}}deleting{{elseif $item.status_id==5}}deleted{{/if}}",
"is_hd": {{if $item.is_hd==1}}true{{else}}false{{/if}}
}{{if !$smarty.foreach.data.last}},{{/if}}
{{/foreach}}]

This code is designed to render list of video items in JSON formatting instead of typical HTML formatting.

NOTE: there are basically 2 general rules of rendering JSON code with Smarty template. Use |json_encode modifier to format strings, as strings need some quoting using double quotes and escaping of system characters. Also use |default:0 modifier to format numbers, this will make sure that at least 0 will be displayed and JSON formatting will not be broken.

In block parameters do the following:

• make sure you configure items_per_page and enable var_items_per_page if you want to display lists with different number of items per page;
• make sure you enable var_from parameter to be able to use pagination;
• make sure you configure sort_by and enable var_sort_by;
• enable all var_xxx parameters under Dynamic filters; you can use them for displaying filtered lists, e.g. by category, or by tag;
• enable var_search parameter and configure other search related options as needed under Search videos by text;
• enable show_categories_info, show_tags_info, show_models_info, show_content_source_info, show_dvd_info, show_user_info under Select additional data for each video only for data that you want to display in your list; please note that these parameters have a huge performance impact.

Now if your page was created with api external ID, you can display your videos list sending GET request to this base URL:

https://kvs-demo.com/api.php?mode=async&function=get_block&block_id=list_videos_api_videos

NOTE: if you want to query data from another block (e.g. categories list, albums list), replace list_videos_api_videos in URL with the unique ID of your other block added to API page.

In Firefox, you should see this URL formatted as JSON array:

In order to use pagination, sorting or filters, simply add the needed parameters to the base URL:

https://kvs-demo.com/api.php?mode=async&function=get_block&block_id=list_videos_api_videos&from=2
https://kvs-demo.com/api.php?mode=async&function=get_block&block_id=list_videos_api_videos&sort_by=rating
https://kvs-demo.com/api.php?mode=async&function=get_block&block_id=list_videos_api_videos&category_id=2

 

Displaying video info

Open API video view block for editing. In template use the following code:

{{php}}
   header('Content-Type: application/json');
{{/php}}

{
"video_id":  {{$data.video_id|default:0}},
"title": {{$data.title|json_encode}},
"description": {{$data.description|json_encode}},
"duration": {{$data.duration|default:0}},
"screen_url": {{$data.screen_url|json_encode}},
"screen_main": {{$data.screen_main|default:0}},
"screen_amount": {{$data.screen_amount|default:0}},
"video_viewed": {{$data.video_viewed|default:0}},
"rating": {{$data.rating|default:0}},
"rating_amount": {{$data.rating_amount|default:0}},
"post_date": {{$data.post_date|json_encode}},
"view_page_url": {{$data.canonical_url|json_encode}},
{{if count($data.categories)>0}}
   "categories": [{{foreach name="data_categories" item="item_categories" from=$data.categories}}{"id": {{$item_categories.category_id|default:0}}, "title": {{$item_categories.title|json_encode}}, "dir": {{$item_categories.dir|json_encode}}}{{if !$smarty.foreach.data_categories.last}},{{/if}}{{/foreach}}],
{{/if}}
{{if count($data.tags)>0}}
   "tags": [{{foreach name="data_tags" item="item_tags" from=$data.tags}}{"id": {{$item_tags.tag_id|default:0}}, "title": {{$item_tags.title|json_encode}}, "dir": {{$item_tags.dir|json_encode}}}{{if !$smarty.foreach.data_tags.last}},{{/if}}{{/foreach}}],
{{/if}}
{{if count($data.models)>0}}
   "models": [{{foreach name="data_models" item="item_models" from=$data.models}}{"id": {{$item_models.model_id|default:0}}, "title": {{$item_models.title|json_encode}}, "dir": {{$item_models.dir|json_encode}}}{{if !$smarty.foreach.data_models.last}},{{/if}}{{/foreach}}],
{{/if}}
{{if count($data.content_source)>0}}
   "content_source": {"id": {{$data.content_source.content_source_id|default:0}}, "title": {{$data.content_source.title|json_encode}}, "dir": {{$data.content_source.dir|json_encode}}},
{{/if}}
{{if count($data.dvd)>0}}
   "dvd": {"id": {{$data.dvd.dvd_id|default:0}}, "title": {{$data.dvd.title|json_encode}}, "dir": {{$data.dvd.dir|json_encode}}},
{{/if}}
{{if count($data.user)>0}}
   "user": {"id": {{$data.user.user_id|default:0}}, "display_name": {{$data.user.display_name|json_encode}}},
{{/if}}
"type": "{{if $data.is_private==2}}premium{{elseif $data.is_private==1}}private{{else}}public{{/if}}",
"status": "{{if $data.status_id==0}}inactive{{elseif $data.status_id==1}}active{{elseif $data.status_id==2}}error{{elseif $data.status_id==3}}processing{{elseif $data.status_id==4}}deleting{{elseif $data.status_id==5}}deleted{{/if}}",
{{if $data.status_id==5}}
   "delete_reason": {{$data.delete_reason|json_encode}},
{{/if}}
{{if count($data.formats)>0}}
   "files": [{{foreach name="data_formats" item="item_formats" from=$data.formats}}{"postfix": {{$item_formats.postfix|json_encode}}, "duration": {{$item_formats.duration|default:0}}, "filesize": {{$item_formats.file_size|default:0}}, "url": {{$item_formats.file_url|json_encode}}}{{if !$smarty.foreach.data_formats.last}},{{/if}}{{/foreach}}],
{{/if}}
"is_hd": {{if $data.is_hd==1}}true{{else}}false{{/if}}
}

In block parameters make sure to enable var_video_id parameter.

Use the following GET request to query video data for any specific video by passing its ID in the URL parameters:

https://kvs-demo.com/api.php?mode=async&function=get_block&block_id=video_view_api_video_view&id=123

In Firefox, you should see this URL formatted as JSON object:

 

Sending signup request

Open API signup block for editing and modify its parameters as needed. Probably you need to activate disable_captcha parameter so that captcha is not required during signup. There is no need to change anything in template, because in most cases you will render signup form in your app and will only use KVS signup block to process requests. In cases with paid access you will need to display access packages to your users, then use this template code:

{{php}}
   header('Content-Type: application/json');
{{/php}}
[{{foreach name="data" item="item" from=$card_packages}}
{
"access_package_id": {{$item.package_id|default:0}},
"title": {{$item.title|json_encode}}
}{{if !$smarty.foreach.data.last}},{{/if}}
{{/foreach}}]

 

In order to use signup functionality you should send POST request to the following base URL:

https://kvs-demo.com/api.php?mode=async&function=get_block&block_id=signup_api_signup

To see which fields should be sent, take a look at default template of signup block, which renders all supported fields:

• action = signup
• username = <username>
• pass = <password>
• pass2 = <password confirmation>
• email = <email>
• ...

 

Also make you to include these fields with each POST request to make sure response is formatted correctly:

• mode = async
• format = json

As a result of your POST request you should get success or failure response with the list of errors.

 

Sending login request

Login functionality is very similar to signup. Open API logon block and configure parameters as needed. Ignore its template code.

In order to log user in you should send POST request to the following base URL:

https://kvs-demo.com/api.php?mode=async&function=get_block&block_id=logon_api_logon

Specify the following data in POST fields:

• mode = async
• format = json
• action = login
• username = <username or email>
• pass = <password>

As a result of your POST request you should get success or failure response with the list of errors.

NOTE: KVS uses PHP session functionality to manage user sessions. This functionality sends PHPSESSID cookie with every response and requires you to send it back with every request. You must send this cookie with every request to have member-specific functionality working.