Oct 102023

Author

6 min read

Headless shopping-cart api tutorial

Total.js is a modern and efficient Node.js framework. In this tutorial, we will show how easy it is to create a headless shopping cart API using Total.js.

Simple Headless Shopping Cart API

In this tutorial, we will show how easy it is to create a headless shopping cart API using Total.js framework. In the following Chapter 2. we will show how easy you can connect a browser with Total.js WebComponents and in our case we will use the webcomponent j-ShoppingCart from https://componentator.com/components/j-shoppingcart/. To finish our project in chapter 3 we will show you how easy it is to create a progressive web application from our single page application in the second chapter.

Getting Started

To get started we take a moment to explain what actualy will happen in the next chapters.

Creating a headless shoppingcart api without any layout and just data is the way to get started writing modern and independent interfaces. Total.js comes in a way, making it a easy task in everbody's daily work. Following the notation of Total.js, you will get all of the benefits the framework provides to you.

The second chapter will just go in detail how to implement and use the Total.js WebComponent j-ShoppingCart and how you can easly integrate the layout of your choice.

The WebComponent is prepared to be synchronize the data object as a singleton. Including the functionality of synchronizing data between the LocalStorage and the server.

In the third chapter of this series, we will extend the single page application and deliver it as a progressive web application with Cache and remote network synchronisation functionality.

So have fun and happy coding.

1. create project folder

We create a new folder for our project and change into it.

$ mkdir totaljs-cart-api
$ cd totaljs-cart-api

2. install Nodejs framework Totaljs v4

We install the Totaljs v4 framework using the nodejs package manager npm.

$ npm i total4

3. create folder structure

We create the necessary folder structure for controllers and schemas:

$ mkdir controllers schemas definitions databases

4. Create a config file

Optional but helpful is a ./config file. If there is a config file in the root folder of the application, this file is read when the application is started and can influence the application and the behavior at runtime.

$ touch config

(optional)

$ echo 'name     : <YOURAPPNAME>' > config

Here are some more informations about Total.js framework configurations:

Configuration docs

5. Create a startup file

We create the index.js startup file in the root folder of the project.

# create the startup file
$ touch index.js

Use your favorite editor and edit the ./totaljs-cart-api/index.js with following content.

// in /index.js
const options = {};
// options.ip = '127.0.0.1';
// options.port = parseInt(process.argv[2]);
// options.unixsocket = require('path').join(require('os').tmpdir(), 'app_name');
// options.unixsocket777 = true;
// options.config = { name: 'Total.js' };
// options.sleep = 3000;
// options.inspector = 9229;
// options.watch = ['private'];
// options.livereload = 'https://yourhostname';

// Enables cluster:
// options.cluster = 'auto';
// options.cluster_limit = 10; // max 10. threads (works only with "auto" scaling)

// Enables threads:
// options.cluster = 'auto';
// options.cluster_limit = 10; // max 10. threads (works only with "auto" scaling)
// options.timeout = 5000;
// options.threads = '/api/';
// options.logs = 'isolated';

var type = process.argv.indexOf('--release', 1) !== -1 || process.argv.indexOf('release', 1) !== -1 ? 'release' : 'debug';
require('total4/' + type)(options);

6. Create the API controller

We create the file /controllers/api.js in the controllers directory and we use the ROUTE() function of Total.js:

# create api controller
$ touch controller/api.js

// in /controllers/api.js

// general cart routes with websocket implementation
exports.install = function() {
    
    // SHOPPING CART REST API implementation
    ROUTE('API  /api/   -cart_query                *Cart    --> query');
    ROUTE('API  /api/   -cart_read/{id}            *Cart    --> read');
    ROUTE('API  /api/   +cart_insert/              *Cart    --> insert');
    ROUTE('API  /api/   +cart_update/{id}          *Cart    --> update');
    ROUTE('API  /api/   -cart_remove/{id}          *Cart    --> remove');

    // Websocket implementation
    ROUTE('API  @api   -cart_query                 *Cart --> query');
    ROUTE('API  @api   -cart_read/{id}             *Cart --> read');
    ROUTE('API  @api   +cart_insert                *Cart --> insert');
    ROUTE('API  @api   +cart_update/{id}           *Cart --> update');
    ROUTE('API  @api   -cart_remove/{id}           *Cart --> remove');
    
    // IMPORTANT: socket route
    ROUTE('SOCKET / @api');

};

We recommend this introduction of Louis to learn more about Total.js API routing. Totaljs API Routing

Totaljs documentation:

API routing

Starting the server

Lets start our server.

$ node index.js 8000

You should see the following console output in your terminal.

> DEBUG PID: 34389 (v4)
====================================================
PID           : 34390
Node.js       : v18.12.1
Total.js      : v4082
OS            : darwin 21.6.0
Memory        : 9.42 MB / 12.21 MB
User          : mike
====================================================
Name          : Headless Shopping Cart API
Version       : 1.0.0
Date          : 2023-10-12 22:26:32
Mode          : debug
====================================================
Directory     : /home/totaljs/apps/totaljs-cart-api
node_modules  : /home/totaljs/apps/node_modules/total4/
====================================================

http://0.0.0.0:8000/

You will see additional informations as output in your console.

With console.log() you see your debugging output right there.

7. NoSQL or TextDB as DB interface

Total.js framework provides a built-in NoSQL system or TextDB that we can use as a database interface. To use this, we add the appropriate functions to our controller or schema.

TextDB definition

This type of TextDB stores documents (objects) with the predefined schema. In other words: you can store documents with fields only that are defined in the Table schema. The table is much faster than the NoSQL database, but it's limited due to the declaring of the schema.

TABLE(name) returns TextDB instance
each database needs defined schema in /config file like example below:

Table schema declared in /config file:

table_TABLENAME  : id:uid,name:string,price:number,dtcreated:date
table_cart       : id:uid,name:string,items:object,price:number,total:number,count:number,dtcreated:date
table_products   : id:uid,name:string,desc:string,price:number,total:number,count:number,date:date

8. create cart schema with built-in NoSQL

In the folder /schemas we create a the cart schema file named cart.js:

# create the schema file schemas/cart.js
$ touch schemas/cart.js

// in /schemas/cart.js

NEWSCHEMA('Cart', function(schema) {

    // define Action
    schema.action('query', {
        action: function($, model){
        
            NOSQL('cart').find().callback(function(err, response) {
                if (err) {
                    $.invalid(err);
                } else
                    $.callback(response);
            });

        }//end action
    });
    
    schema.action('read', {
        input: '*id:string',
        action: function($, model){
            $.callback([]);
        }
    });
    //
    schema.action('insert', {
        input: '*name:string,*price:number',
        action: function($, model){
        
            NOSQL('cart').insert($.body).callback(function(err, response) {
                if (err) {
                    $.invalid(err);
                } else
                    $.success();
            });// end NOSQL
            
        }//end action
    });
    
    schema.action('update', {
        input: '*id:string, *amount:number',
        action: function($, model){
        
            NOSQL('users').update($.body).where('id', $.params.id).callback(function(err, response) {
                if (err) {
                    errorHandler(err, res);
                    return;
                } else
                    $.success();
            });
            
        }//end action
    });
    
    schema.action('remove', {
        input: '*id:string',
        action: function($, model){
        
            NOSQL('cart').remove().where('id', $.params.id).callback(function(err, response) {
                if (err) {
                    $.invalid(err);
                } else
                    $.success();
            });
            
        }//end action
    });
});

Total.js Schemas are one of the most used parts of the Total.js framework. Schemas offer you full control over incoming data. We can execute schemas from routes directly as we do in our example. (look to ROUTE() method ).

9. Testing the API

You can use any REST API client tool like Curl, Postman or SWAGGER.

Let's say we have /api/cart_insert endpoint for adding products using $ curl:

Use the "POST" request type
Enter the full URL http://localhost:8000/api
choose request body-type "JSON"
Enter the api schema action like cart_insert
Enter the data object with a product data singleton in JSON format

Curl POST JSON Syntax:

Method: POST 
Content-Type: application/json
{
   "schema": "schema_name/{dynamic_arg_1}/{dynamic_arg_2}?query=arguments",
   "data": {}
}

We can use the command curl to send the api schema.

$ curl -X POST [URL]
       -H "Content-Type: application/json" 
       -d "[JSON data]"

Update: Curl is as well included in Windows, no need to run it via PowerShell.

First you need to download the cURL executable. For Windows 64bit, download it from here and for Windows 32bit download from here After that, save the curl.exe file on your drive.

To use it, just open the command prompt and change the directory to the folder you downloaded curl.exe and type in if you copied the executable to C:\

% C:\curl http://localhost

Curl POST API Call Example:

To follow the definition of j-ShoppingCart singleton, we use the following json definition:

https://componentator.com/components/j-shoppingcart/

{
    items: [
        {
            name: String,
            price: Number,
            total: Number,
            count: Number,
            date: Date
        }
    ],
    price: Number,
    total: Number,
    count: Number
}

Singleton Description:

1. items: This is an array containing multiple cart item objects. Each item object has the following properties:

name: A string representing the item's name.
price: A number representing the price of an individual item.
total: A number representing the total price of the item.
count: A number indicating the number of units of this item.
date: A date that might represent the purchase or manufacture date of the item.

2. price: A number representing the total price of all cartitems in the list. This could potentially be the sum of all "total" values from the "items" array.

3. total: A number representing an overall total value. It represents the final price after applying discounts, delivery costs or taxes.

4. count: A number representing the total quantity of all items in the list. Sum of all "count" values from the "items" array.

Define temporary fake-data in your terminal with export as a environment cariable.

# declare cart items in singleton structure
$ export CART_ITEMS='{"items": [{name: "product 1", price: 8.00, total: 8.00, count: 1 }], price: 8.00, total: 8.00, count:1}'
# just a check
$ echo $CART_ITEMS
# {"items": [{name: "product 1", price: 8.00, total: 8.00, count: 1 }], price: 8.00, total: 8.00, count:1}

# declare api call object
$ export API_OBJECT='{"schema":"cart_insert", "data":'${CART_ITEMS}'}'
# just to check
$ echo $API_OBJECT
{"schema":"cart_insert", "data":{"items": [{name: "product 1", price: 8.00, total: 8.00, count: 1 }], price: 8.00, total: 8.00, count:1}}
# a short helper env variable
$ export API_ENDPOINT=http://localhost:8000/api/

If everything works like expacted, you should see the nested environment variables in your terminal console.

Lets try our first api call.

# <your-api-address>:<your-ip-port>, localhost:8000
$ curl -X POST $API_ENDPOINT  \
     -H 'Content-Type: application/json' \
     -d $API_OBJECT

Response object

{"success":true, "id": <returned-insert-id>}

Preparing CRUD testing

Inserting cart items.

# declare api create call object
$ export API_CREATE='{"schema":"cart_insert", "data":'${CART_ITEMS}'}'

# CRUD - CREATE API Call
$ curl -X POST http://<your-ip-adress>:<your-port>/api/  \
     -H 'Content-Type: application/json' \
     -d $API_CREATE

Read the API with specific cart item id {"schema":"cart_read/1234567890"}

# declare api read call object
$ export API_READ='{"schema":"cart_read/<id>"}'

# CRUD - READ API Call
$ curl -X POST http://<your-ip-adress>:<your-port>/api/  \
     -H 'Content-Type: application/json' \
     -d $API_READ

cURL UPDATE API Call

# declare api update call object
$ export API_UPDATE='{"schema":"cart_update", "data":'${CART_ITEMS}'}'

# CRUD - update api call
$ curl -X POST http://<your-ip-adress>:<your-port>/api/  \
     -H 'Content-Type: application/json' \
     -d $API_UPDATE

cURL DELETE API Call

# declare api remove call object
$ export API_DELETE='{"schema":"cart_delete/<id>"}'

# CRUD - delete api call
$ curl -X POST http://<your-ip-adress>:<your-port>/api/  \
     -H 'Content-Type: application/json' \
     -d $API_DELETE

WebSocket message:

API Websocket payload:

{
    "TYPE": "api",
    "callbackid": "CUSTOM_CALLBACK_ID", // The value will be returned back
    "data": {
        "schema": "schema_name/{dynamic_arg_1}/{dynamic_arg_2}?query=arguments",
        "data": {}
    }
}

Look to the difference building the json object to send to the websocket api implementation.

{
    "TYPE": "api",
    "callbackid": "123456789", // The value will be returned back
    "data": {
        "schema": "cart_insert",
        "data": $CART_ITEMS
    }
}

How to test the websocket api implementation:

It can be tricky, but with this cURL command it should be possible get in touch with the Total.js Websocket API Implementation.

# Testing the websocket api connection 
curl --include \
   --header "Connection: Upgrade" \
   --header "Upgrade: websocket" \
   --header "Sec-WebSocket-Key: qwerty" \
   http://<your-ip-address>:<your-port>/

Advance the API with a payment provider

How to implement a payment gateway provider like paypal, molly or stripe?

If you are interessted in it, just leave a line at info@totaljs.com and we will get in touch.

Conclusion:

With Total.js, we can create a powerful API in a short time. The framework's clear structure and intuitive methods speed up the development process significantly. Inlcuding a realtime websocket based api structure, it is now easy to connect with several clients written in Rust, Go, PHP, C/C++, Ruby and more.