My accountGet started
Oct 142022
Total.js Platform
2 min read

Tutorial series - #5 API routing and QueryBuilder

Discover API routing mechanism and explore wonderful database queries with QueryBuilder

Tutorial series - #5 API Routing and Querybuilder

In this tutorial you will discover two amazing features of Total.js : API routing and Querybuilder. API routing is newly added to total4 as an extra functionality. Querybuilder is a simple ORM that is used within total.js apps with multiple databases compatibility.

API routing

API routing is an internal mechanism used to expose API endpoints in a very simple way. The mechanism is designed to focus on handling maximum number of operations with minimum enpoints. Therefore API routing only works with Total.js Schema and their operations.

How does it work?

You can create one enpoint (e.g /api/) and use it to target infinite number of operations within your application. All you have to do is call that endpoint with POST method and have in the body of the request, a json payload to specify what operation of what schema to target.

Example :

Download empty project

Declare your API routes

Create Schema and operations

Call endpoint from external



The request body is JSON format and expects two parameters:

  • schema ---> (schema_name/{dynamic_arg_1}/{dynamic_arg_2}?query=arguments)

to specify schema (supports params and query).

  • data ---> data payload (optional).

Good to know

The routing can contain two times +/- characters.

  • First : ROUTE('+API ...') or ROUTE('-API ...') for authorization purpose. (Read more here).
  • Second +schema_name or -schema_name to specify if data reception is expected or not.

Websocket API

Yes. The API Routing supports the websocket protocol and we recommand it too. Its declaration is same like the standard API Routing, except that the route must contain identifiers in the form @YOUR_NAME instead of relative URL address. Let us try it:

Declare your Websocket API routes

Websocket message:


Querybuilder is a lightweight ORM (Object Relational Mapping) that supports various database engines. QueryBuilder acts like an abstraction layer of the database management system in order to let you manipulate data in a comfortable way. Without ORM in your application, all your database queries would look like this 😢 :

Instead of that, you can use Querybuilder 😋 which gives you many benefits like:

  • database operations
  • query operations for filtering data
  • automatic error handling operations
  • operations audits
  • etc

Querybuilder has many implementations and support many database engines:


Let us move quickly to the example. We are taking our API Routing example above and we are updating schema file.

QueryBuilder with NOSQL

Replace with the following

QueryBuilder with Postgresql

First: install QueryBuilder inplementation for postgresql

Second: Connect to your postgresql database

Replace with the following