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
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:
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.
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.
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
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).
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.
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.
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.