Hello Rest Service

Overview

In this tutorial, we’re going to show how Knot.x can be used to quickly transform your
static website into a dynamic one. Instead of a manually coded HTML document presenting available books,
we’re going to use an HTML template and populate it with data loaded from an external service.

This article concentrates on the steps required to integrate with a service using Knot.x, instead of client side JavaScript.
In the next article we are going to compare that solution with a frontend integration.

What you’re going to learn:

How to transform static HTML into dynamic content

How to configure Knot.x to use simple REST services to get data

How to use data from such services to dynamically populate HTML

If you want to skip the configuration part and simply run the demo, please checkout
Github/hello-rest-service and follow the README.md to see how to run it.

Our application

Knot.x has the ability to combine service data with HTML in a very efficient manner.
It can get a JSON response from a service and then, using the Handlebars engine, render the dynamic part.
This can be achieved without any custom code – it is only a matter of configuration.

The diagram below depicts how a request from a user is handled by the Knot.x application.

As soon as a request comes to Knot.x, it causes an HTML template to be fetched from the repository.
In real cases, the repository is usually an external system, like a CMS, that is available over HTTP.
However, for the purpose of demonstration, we simply get those HTML pages from the local filesystem using
the Knot.x File system repository connector.

At this point, Knot.x detects all services required to render your dynamic page. Actual service
endpoints are defined in Knot.x configuration, on the HTML level, each dynamic part simply specifies
which endpoint it requires (by name). The unique set of services required, initiates process of
querying services for the data, followed by an invocation of the Handlebars engine. The Handlebars engine
combines the markup and the data obtained form the services to produce the final markup of the dynamic HTML snippet.

Finally, the rendered HTML is returned to the requesting user.

Start with Knot.x

Now it’s the time to prepare the environment required to run Knot.x.
First, let’s download all required files from the Nexus repository and create the folder structure that we’re going to use in this tutorial.

You can try running Knot.x application with ./run.sh command. But for now stop it and follow next steps to configure it to do something useful.
More details about Knot.x deployment and setup can be found here.

Configure Knot.x

As we already have a base Knot.x setup, let’s start adapting it to our needs.
If you open the knotx-config.json file in a text editor, you wil see that it contains an array
containing a list of modules. These are the Knot.x modules
that are going to be started.

Repository configuration

As mentioned before, we are going to fetch an HTML template from our local file system.
Knot.x is shipped with a dedicated module called FileSystemRepositoryConnector designed
for this very purpose. You need set up the connector to use the /library folder from where requested HTML files
(containing Handlebars snippets) will be fetched.

Different repository connectors can be used at the same time, so we need to tell Knot.x which one should be used to process a given request.
You can use regular expressions to match request URIs to different repositories.

Our template file (books.html) is available in the html folder, under the library root folder.
It means, that our target is that whenever a user performs a GET request for /html/books.html,
Knot.x should look for the /html/books.html file inside the /library folder on the local file system.
In order to achieve that, we need to tell KnotxServer module that:

Any request to /html/.* should fetch a template from the file system repository.

You might notice the address field in the above configuration. This is the internal event bus
address of the Repository Connector, in this case it’s the address of our File System Repository Connector.

All configuration options and default values, such as address fields, for each Knot.x module are described in the documentation.

Book service configuration

The Service Knot module is responsible for an integration with
external services.
The configuration of this module consists of services which can be used in any template
processed by Knot.x. Each service has an associated name, that is actually being used on HTML
level and an address of the Adapter that is handling communication with the outside world.
This kind of mapping makes possible a quick substitution of the acutal service being used.
You can supply multiple Adapter modules for any kind of protocol or interface. And as long as
the data provided by your adapter implementation has the same structure, you can swap it for another implementation.

Each service request using this name will be done under the path /books/v1/volumes?q=java

As you see we specified the URI but not the address of the service. The actual endpoint will be
configured on the Adapter level. This configuration approach allows you to have two services
defined, each using the same adapter (and therefore the same endpoint), but have a different name and path.

The adapter address points to the HttpServiceAdapter
that is available out of the box. So, as you can suspect, the remaining configuration
will happen in the Adapter module.