Kentico EMS & Xperience

Create JSON API endpoints in the Kentico Portal Engine

August 22, 2017

You might have noticed that Kentico released a new product Kontent.ai. It has a fancy UI for managing content and easy-to-use API endpoints talking to you in JSON. This gives you a lot of flexibility and you can render and manipulate data on the server or the client side.

In Kentico CMS/EMS you can operate data only server side by default. However, with a little effort you can create a JSON API endpoints in Kentico Portal Engine that allow you to work with data on the client side.

Why would I need endpoints in Kentico CMS/EMS?

Requesting data on the client side with AJAX is fast and invisible to a website visitor. Having data in the JSON format allows you to easily use javascript libraries that make your data interactive. This all could be achieved in the Kentico Portal Engine with use of web parts and QueryString macros.

Normally, in Kentico you communicate with server via postbacks which is not really fast and responsive. Moreover, this requires you to code in the Kentico back-end.

What is an endpoint?

An endpoint represents a service that is approachable by a URL.

 http://localhost/items?documentname=example

Really simple example. Imagine you would request this endpoint via jQuery.ajax().

jQuery.ajax({ 
  url: 'http://localhost/items?documentname=example', 
  type: 'GET', 
  dataType:'json', 
  error: function(e) {console.error(e);}, 
  success: function(data) {console.log(data.items);}
});

And you expect a JSON response processed by jQuery so you end up with an array of objects.

[ { documentID: 1, nodeAliasPath: "/example" }, { documentID: 2, nodeAliasPath: "/page/example" } ]

How to make this happen in the Kentico Portal Engine?

The core of the matter is the /items page that takes the documentname url parameter and returns a list of pages with specified DocumentName.

If you think of using the Repeater web part you're almost right. However, if you use just the Repeater web part, you will get a full page output with all the html tags like <html><head>...</head><body>...</body></html>. But we need pure JSON.

Kentico has a magic web part called Custom response that returns pure output with specified content type. Unfortunately, the web part is able to return only static text. We need a repeater with the magic of the Custom response web part.

I have prepared 2 web parts that combine Custom response and the Repeater/Repeater with custom query web parts. You can download and import packages of those web parts for Kentico 10.0.13:

Custom response repeater (originally developed by Jan Hermann) – Derived from the Basic repeater web part. Could be used with the Data source web part or just for repeating pages.
Custom response repeater with custom query – Derived from the Repeater with custom query web part.

With use of the web parts you can get data from Kentico as you normally would. If you set Content type to JSON and specify Content before, Content after and Transformation web part properties to render data in JSON format, your endpoint is ready to use.

Practical example

Download and import the Custom response repeater and/or Custom response repeater with custom query web part in your Kentico project.
In the Pages application create a page. Set Document name to items. Place the web part in there.
1. Content before: {"items": [
2. Content after: ]}
3. Transformation (Text/XML):
  {"documentID": {% DocumentID %}, "nodeAliasPath": "{% NodeAliasPath %}"}{% DataItemCount - DataItemIndex == 1 ? "" : ", " %}
4. Content type: application/json
5. Where condition:
  {% QueryString.documentname != "" ? "DocumentName='" + SQLEscape(QueryString.documentname) + "'" : "" #%}
6. Set Path and/or Page type as well to define what content should be rendered.
On other page that is intended to show the data place the Javascript web part with code that calls AJAX request. Example:

jQuery.ajax({ 
  url: 'http://localhost/items?documentname=example', 
  type: 'GET', 
  dataType:'json', 
  error: function(e) {console.error(e);}, 
  success: function(data) {console.log(data.items);} 
});

Make sure the jQuery library is included. When you request the page you should see output in the browser console.

Final thoughts

Hope the article explained the concept of endpoints in the Kentico Portal Engine well. From this point you should be able to adjust the concept to your scenario.

Notes

Always make sure your Where conditions in repeaters that use QueryString are safe from SQL injections. Read article from Juraj Komlosi.
The {% DataItemCount - DataItemIndex == 1 ? "" : ", " %} expression in the transformation renders the ", " string for all items except the last one. {% DataItemCount - DataItemIndex == 1 %} is an alternative for the <%# IsLast() %> method in ASCX transformations.