Example QEWD Back-end codebase that adheres to the RealWorld spec and API.

This repo is functionality complete - PR’s and issues welcome!

Rob Tweed rtweed@mgateway.com
25 January 2017, M/Gateway Developments Ltd http://www.mgateway.com

Updated: 28 October 2020

Twitter: @rtweed

Google Group for discussions, support, advice etc: http://groups.google.co.uk/group/enterprise-web-developer-community

About qewd-conduit

qewd-conduit is a full implementation of the REST back-end for the
RealWorld Conduit
application using QEWD.

qewd-conduit requires QEWD to be installed on your server.
QEWD itself is a Node.js-based Web Application & REST run-time platform.

QEWD is available in both Dockerised and natively-installed formats. Which you choose
is up to you, but even for the non-Dockerised version, the installation and configuration
process is very quick and almost completely automated.
You’ll find that you can install qewd-conduit and have it fully up and running in
literally just a few minutes, so there are really no reasons not to try it out!

qewd-conduit can work with a number of so-called Global Storage databases, including:

• InterSystems IRIS
• InterSystems Caché
• YottaDB

The Dockerised version of QEWD includes a pre-installed and pre-configured instance
of YottaDB, but it can also be quickly and simply reconfigured to connect to a Caché or IRIS
database over a networked connection.

QEWD applies an abstraction known as QEWD-JSdb to these databases,
which makes them all behave identically as a Document Database and Persistent JavaScript Objects.
Applications written in JavaScript for QEWD will run identically on all three supported databases.

Read my article
that explains the rationale and objectives of QEWD.

Since the back-end specification of the RealWorld Conduit application is
fully documented
and implemented using
several other technologies and/or frameworks,
it provides a great way of comparing and contrasting the different development approaches
used for each option.

Although QEWD is a Node.js-based platform, you’ll see that the way in which the back-end has
been able to be developed is quite different from what you’d expect. Whilst it’s all
been written in JavaScript, the persistent JavaScript Object manipulation logic
(which is physically interacting with the database) is not asynchronous.
That’s possible due to QEWD’s master process / queue / worker process-pool
architecture.

The RealWorld Conduit initiative also allows direct comparisons to be made in terms of
back-end performance. I think you’ll be favourably impressed by the performance of
qewd-conduit which is largely down to the lightning-fast performance of the underlying
databases (YottaDB, IRIS or Caché) and the
in-process Node.js database interface used by QEWD.

What may be less easy to appreciate is the speed of development when using the different
RealWorld Conduit back-end technologies. I can tell you that, in the case of qewd-conduit,
the entire back-end was implemented from scratch in just 2 man-days, including the time taken
to read up on and understand the application’s objectives, requirements and APIs. Part of
the speed of development comes from not having to worry about asynchronous logic, but it’s
also due to the very high-level database abstraction of
QEWD-JSdb.

WebSocket Support

Uniquely amongst RealWorld Conduit back-end implementations, qewd-conduit not only
implements the full suite of Conduit REST APIs, but also provides equivalent APIs that
are accessed via WebSockets.

These make use of QEWD’s built-in WebSocket support, and require specially-adapted
versions of the RealWorld front-ends that use the
QEWD-Client to communicate securely
via WebSockets with the qewd-conduit back-end.

Your qewd-conduit installation includes a pre-installed and pre-configured copy
of the wc-conduit front-end client which
supports both the REST and WebSocket APIs of qewd-conduit.

Alternatively, Ward De Backer has created a
suitably-adapted version of the Vue.js RealWorld front-end application
that you can use to try out the qewd-conduit WebSocket interfaces. For instructions, see
later in this document.

Installing and Running the qewd-conduit Back-end

See the instructions for the following platforms:

• IRIS running on Windows
• IRIS running on Linux or OSX
• YottaDB running on Linux or Raspberry Pi
• QEWD Docker Container

Installing and Running the RealWorld Front-End

qewd-conduit implements the RealWorld REST API specification, so you can install and
use any of the authorized client interfaces, the details and instructions for which
can be seen here.

Your qewd-conduit installation also includes a pre-installed and pre-configured copy
of the wc-conduit front-end client.
This uses our WebComponent-based mini-framework known as
mg-webComponents, to
provide a very fast and lightweight RealWorld front-end client. The
pre-installed version is configured to use your qewd-conduit back-end’s
REST or WebSocket APIs. It can be re-configured in a matter of seconds to use any
other available Conduit back-end (in which case you must only use the REST API version
of wc-conduit).

If you decide to use a different RealWorld front-end client, ensure you
configure it to send its REST requests to the endpoints provided by
your installed QEWD Conduit back-end.

As an example, Ward De Backer has provided:

• detailed documentation
  on how to install and use the Vue RealWorld Example application client
  with a qewd-conduit Back-end
• detailed documentation
  on how to install and use the React Redux RealWorld Example application client
  with a qewd-conduit Back-end
• detailed documentation
  on how to install and use the Angular RealWorld Example application client
  with a qewd-conduit Back-end

His documentation
also explains how to use his
specially-adapted WebSocket-enabled version
of this same Vue.js client. You’ll then be able to compare and contrast the relative performance of
the REST and WebSocket interfaces for the same set of APIs (which, within qewd-conduit,
as you might expect, invoke the exact same underlying API handler logic modules).

How the qewd-conduit Back-end Works

qewd-conduit has been developed following the standard, so-called
QEWD-Up approach (click for details).

In summary:

• the system configuration is described in the /configuration/config.json file;

• the REST API routes are described in the /configuration/routes.json file. Each
  route is described as an object that defines its:

  • URI;
  • HTTP method; and
  • handler name

    • the correspondingly-named handler modules can be found in the /apis directory

    • the handler logic is in each handler module’s index.js file.

      Every handler module
      has the same signature, with all the incoming REST request’s information being
      represented appropriately in the args argument.

      On completion, each handler module returns its JSON response object as the sole argument
      of a special QEWD-supplied function called finished(). This finished() function returns the
      JSON response to the REST client and also releases the QEWD Worker process back to
      the available Worker pool.

• the WebSocket interfaces can be found in the /qewd-apps/qewd-conduit directory. There is
  a named handler module for each supported WebSocket message, and these correspond by name to
  the qewd-conduit REST handler names. if you look at the index.js file for each WebSocket
  handler module, you’ll see that they are all simply wrapper stubs, calling another module
  that converts the WebSocket message contents into the corresponding REST handler module’s
  args object, and then invokes the corresponding REST handler method. In other words, the
  WebSocket interface is simply (but very effectively!) a wrapper around the REST handler methods.

• the physical database handling for the persistent objects used in qewd-conduit is encapsulated as
  as set of APIs which are used by the various REST API handler methods. This is done in order to
  keep all the physical database handling logic for each persistent object into just one place, rather
  than it being spread around within the REST API handler methods.

  The database objects are described in the /conduit/db directory

  In there, you’ll see that there are just three persistent objects in qewd-conduit,
  with corresponding handler API modules:

  • users (/conduit/db/users.js)
  • articles (/conduit/db/articles.js)
  • comments (/conduit/db/comments.js)

  Each of these modules defines the CRUD methods used to maintain and access the persistent
  object using the QEWD-JSdb abstraction methods.

  The QEWD-JSdb modelling of these persistent Objects, and how they map to
  physical Global Storage is
  described in this article.

Inspecting the qewd-conduit Database

qewd-conduit stores and maintains the Conduit data in three Globals:

• conduitUsers
• conduitArticles
• conduitComments

You can use any of the utilities provided by IRIS or Caché to inspect these Globals.

You can also use the qewd-monitor or qewd-monitor-adminui applications to inspect them.
In particular, check out the qewd-monitor-adminui QEWD JSdb Inspector option which
provides a graphical representation of the hierarchy tree of each Global through which
you can navigate.

License

Copyright (c) 2017-20 M/Gateway Developments Ltd,
Redhill, Surrey UK.
All rights reserved.

http://www.mgateway.com
Email: rtweed@mgateway.com

Licensed under the Apache License, Version 2.0 (the “License”);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0                           

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an “AS IS” BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.