Introduction

fetch("https://api-v1.kenzap.cloud/", {
  method: "post",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer your_api_key"
  },
  body: JSON.stringify({
      query: {
          products: {
              type:       "find",
              key:        "ecommerce-product",
              fields:     ["_id", "img", "status", "price", "title"],
              limit:      25
          }
      }
  })
})
.then(response => response.json())
.then(response => {

  console.log(response)

})

Welcome to Kenzap Cloud API. You can use this API to access and manage the data of your installed Extensions in the Kenzap Cloud Space.

Extensions are building blocks of Kenzap Cloud allowing you to create progressive web applications for businesses of all sizes. All extensions are open-sourced. You can explore some extension examples on Github.

The purpose of Kenzap API is to:

• speed up the development time of complex applications
• bring highly performant user experience
• ensure consistency in the ecosystem of Cloud Extensions

The API examples are provided in JavaScript language. The query on the right side demonstrates how to return 25 records of products stored in the Cloud Space of the E-commerce extension.

Authentication

There are two types of authorization methods:

• API key authorization
• User token authentication

API Key Authorization

fetch("https://api-v1.kenzap.cloud/", {
  method: "post",
  headers: {
    "Accept': 'application/json",
    "Content-Type': 'application/json",
    "Authorization': 'Bearer your_api_key"
  }
})

API key authorization is designed for backend communication between servers. This type of method should not be used in frontend production sites.

All Kenzap Cloud API requests must contain an API key in a header that looks like the following:

Authorization: Bearer your_api_key

You can register a new API key under the Kenzap Cloud Access dashboard.

User Token Authentication

fetch("https://api-v1.kenzap.cloud/", {
  method: "post",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Kenzap-Token": "kenzap_user_token",
    "Authorization": "Bearer your_api_key"
  }
})

User token authorization is designed for applications that need to manipulate data from the frontend. For example, a user places an order to the E-commerce extension.

All Kenzap Cloud API requests must contain API key and Kenzap user token in a header that looks like the following:

Authorization: Bearer your_api_key

Kenzap-Token: kenzap_user_token

You can register a new API key under the Kenzap Cloud Access dashboard. You can retrieve kenzap_user_token from kenzap_token cookie when the user is authorized to the Kenzap Cloud.

API Key Parameters

• Access type
  • Frontend - frontend queries (requires kenzap_user_token).
  • Backend - server side communication.
• Permissions
  • Read only - allow read queries only.
  • Read & write - allow read and write queries.
• Isolated
  • Yes - access data generated by the same API key or user.
  • No - access any data including data with the isolated parameter set to "Yes".

Query Structure

By default all queries are sent as JSON paylod in the POST request body.

HTTP Request

POST https://api-v1.kenzap.cloud/

JSON Payload

"query": {
    "records": {
        "type":       query_type
    }
}

query: { records: { type: query_type } }

Query Types

Create

This type of query creates new Kenzap Cloud record and returns 40 character generated ID string.

Create Parameters

"query": {
    "record": {
        "type":       "create",
        "key":        key,
        "data":       data
    }
}

The table below demonstrates various parameters that you can use to customize your find query.

Create key

"key": "ecommerce-product"

This parameter specifies which extension data to query within the Cloud Space. Key names are arbitrary, meaning that each extension is having its own set of available keys. Think of keys as tables in the context of relational databases.

For example, E-commerce extension keys:

• ecommerce-product
• ecommerce-settings
• ecommerce-order

MyTicket extension keys:

• myticket-settings
• myticket-layouts
  

Create data

"data": {
          "title":        title,
          "description":  description,
          "status":       status.
          "img":          [],
          "price":        price
        }

Kenzap Cloud does not follow strict schema, meaning that any extension can define its own data structure and columns.

This parameter contains all payload data that you want to permanently store in the Kenzap Cloud.

Create Examples

Create new product

Create new product:

fetch("https://api-v1.kenzap.cloud/", {
  method: "post",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer your_api_key"
  },
  body: JSON.stringify({
      query: {
          product: {
              type:   "create",
              key:    "ecommerce-product",
              data:   "data": {
                                "title":        "California Sushi",
                                "description":  "A set of 6 pieces, comes with free ocha.",
                                "status":       "published".
                                "price":        "24.50"
                              }
          }
      }
  })
})
.then(response => response.json())
.then(response => {

  console.log(response);

})

Insert new E-commerce product with the following values:

• California Sushi for title.
• A set of 6 pieces, comes with free ocha for description.
• published for status.
• 24.50 for price.

Find

This type of query performs a search operation in the Cloud. It may return one or multiple records.

Find Parameters

"query": {
    "records": {
        "type":       "find",
        "key":        key,
        "id":         id,
        "fields":     fields,
        "term":       [
                        {
                            "field": field,
                            "relation": relation,
                            "type": type,
                            "value": value
                        }
                      ],
        "search":     {         
                        "field": field,
                        "s": s
                    },
        "sortby":   {
                        "field": field,
                        "order": order
                    },
        "groupby":  [
                        {
                            "field": field,
                        }
                    ],
        "count":    count,
        "sum":      sum,
        "limit":    limit,
        "offset":   offset
    }
}

The table below demonstrates various parameters that you can use to customize your find query.

Find key

"key": "ecommerce-product"

This parameter specifies which extension data to query within the Cloud Space. Key names are arbitrary, meaning that each extension has its own set of available keys. Think of keys as tables in the context of relational databases.

For example, E-commerce extension keys:

• ecommerce-product
• ecommerce-settings
• ecommerce-order

MyTicket extension keys:

• myticket-settings
• myticket-layouts
  

Find fields

"fields": [ 
            "_id", 
            "title", 
            "created"
          ]

Kenzap Cloud does not follow a strict schema, meaning that any extension can define its data structure and columns. Some fields parameter examples:

• "*" - query all fields
• ["_id", "title", "created"] - query system _id, title and created fields only
  

Find id

"id": "e3de841f54b88997f2e18cfd60dd06ebb956db22"

You can query individual record by its unique ID. IDs are generated by the Cloud when data record is first inserted into the database. ID example:

e3de841f54b88997f2e18cfd60dd06ebb956db22

Find term

"term": [ 
          { 
            "field": "created", 
            "relation": ">=", 
            "type": "numeric", 
            "value": 1640093421 
          }, 
          { 
            "field": "status", 
            "relation": "=", 
            "type": "string", 
            "value": "completed" 
          } 
        ]

You can add one or multiple terms to your queries by providing additional instructions on which fields to query and specify query relation. Examples:

• { "field": "status", "relation": "=", "value": "completed" } - return records where status fields equals to "completed".
• Refer to the right pane for a more complex query term example.
  

Available term relations:

• > - greater than
• < - less than
• >= - greater than or equals
• <= - less than or equals
• = - equals

Available term types:

• string - consider provided value as string
• numeric - consider provided value as numeri

Find search

"search": {
            "field": "title",
            "s": "sushi"
          }

You can perform a case insensitive search within all records of the specified field.

"search": { "field": "title", "s": "sushi" }

Find sortby

"sortby": {
            "field": "created",
            "order": "DESC"
          }

You can sort orders by a specified field. Refer to the right pane for sortby example.

Available sortby orders:

• DESC - sort in descending order
• ASC - sort in ascending order

Find groupby

"groupby": [
              {
                "field": "category"
              }
            ]

You can aggregate records by a specified field. For example, this operation might be useful, if you want to count the total amount of sold products but want to split these records into multiple categories.

• groupby: [ { field: "category" } ]

Find limit

"limit": 25

Limit set the maximum number of queried records to return. If value is not provided it equals to 10 records per query. By providing value that is grater than 10 limit increases total number of returned records.

limit: 10

Find offset

"offset": 10

Indicates how many records to skip from the beginning of the query response. By default, this value equals 0.

offset: 10

Find Examples

Find First 25 Products

Find First 25 Products:

fetch("https://api-v1.kenzap.cloud/", {
  method: "post",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer your_api_key"
  },
  body: JSON.stringify({
      query: {
          products: {
              type:       "find",
              key:        "ecommerce-product",
              fields:     ["_id", "img", "status", "price", "title"],
              limit:      25
          }
      }
  })
})
.then(response => response.json())
.then(response => {

  response.products.forEach(product => {

    console.log(product);

  })
})

The above command returns JSON structured like this:

{
 ...
}

The following example demonstrates how to query the first 25 records stored under the ecommerce-product key.

Query fields:

• _id - cloud assigned record ID.
• img - list of available product images
• status - product status
• price - product price
• title - product title

Search for "Sushi" Products

Search for "Sushi" Products:

fetch("https://api-v1.kenzap.cloud/", {
  method: "post",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer your_api_key"
  },
  body: JSON.stringify({
      query: {
          products: {
              type:       'find',
              key:        'ecommerce-product',
              fields:     ['_id', 'id', 'img', 'status', 'price', 'title', 'updated'],
              search:     {   
                              field: 'title',
                              s: "sushi"
                          },
              sortby:     {
                              field: 'title',
                              order: 'DESC'
                          }
          }
      }
  })
})
.then(response => response.json())
.then(response => {

  response.products.forEach(product => {

    console.log(product);

  })
})

The above command returns JSON structured like this:

{
 ...
}

The following example demonstrates how to query the first 25 records stored under the ecommerce-product key.

Query fields:

• _id - cloud assigned record ID.
• img - list of available product images
• status - product status
• price - product price
• title - product title

Generate Analytics Report

Generate Last 30 days Analytics Report:

let today = "2023-05-01T00:00:00.001Z"

fetch("https://api-v1.kenzap.cloud/", {
  method: "post",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer your_api_key"
  },
  body: JSON.stringify({
      query: {
          by_country: {
              type:       'find',
              key:        'analytics',
              fields:     ['cc'],
              count:      ['cc'],
              term:{
                  field:  'created',
                  relation:'>',
                  type:   'numeric',
                  value:  (Date.parse(today)  / 1000 | 0) - 60 * 60 * 24 * 30
              },
              groupby: [
                  {
                      field: 'cc'
                  }
              ],
              sortby: {
                  field: 'cc_count',
                  order: 'DESC'
              },
              offset: 0,
              limit:  300
          },
          by_sessions: {
              type:       'find',
              key:        'analytics',
              fields:     ['ymd'],
              count:      ['ymd'],
              term:[
                  {
                      field:  'created',
                      relation:'>',
                      type:   'numeric',
                      value:  (Date.parse(today)  / 1000 | 0) - 60 * 60 * 24 * 30
                  },
                  {
                      field:  'tag',
                      relation:'=',
                      type:   'string',
                      value:   'session:5s'
                  },
              ],
              groupby: [
                  {
                      field: 'ymd'
                  }
              ],
              sortby: {
                  field: 'ymd_count',
                  order: 'DESC'
              },
              offset: 0,
              limit:  31
          }
      }
  })
})
.then(response => response.json())
.then(response => {

  response.by_country.forEach(country => {

    console.log(country);

  })

  response.by_sessions.forEach(session => {

    console.log(session);

  })
})

The above command returns JSON structured like this:

{
 ...
}

The following example demonstrates how to generate an analytics report that can be used, for example, in Google Charts API. Query fields:

• _id - cloud assigned record ID.
• img - list of available product images
• status - product status
• price - product price
• title - product title

Update

This type of query updates exiting record stored in the Kenzap Cloud. It is mandatory to provide a 40-character record ID.

Update Parameters

"query": {
    "record": {
        "type":       "update",
        "key":        key,
        "id":         id,
        "data":       data
    }
}

The table below demonstrates various parameters that you can use to customize your find query.

Update key

"key": "ecommerce-product"

This parameter specifies which extension data to query within the Cloud Space. Key names are arbitrary, meaning that each extension is having its own set of available keys. Think of keys as tables in the context of relational databases.

For example, E-commerce extension keys:

• ecommerce-product
• ecommerce-settings
• ecommerce-order

MyTicket extension keys:

• myticket-settings
• myticket-layouts
  

Update id

Unique Kenzap Cloud record ID. It is generated when the record is first created in the Cloud.

"id": "00232c6e9024c0d8d064af7754e1c60580fe4407"

Update data

"data": {
          "title":        title,
          "description":  description,
          "status":       status.
          "img":          [],
          "price":        price
        }

Kenzap Cloud does not follow strict schema, meaning that any extension can define its own data structure and columns.

This parameter contains all payload data that you want to permanently store in the Kenzap Cloud.

Existing fields are mapped with the provided schema and are updated with the new value.

Update Examples

Update existing product

Update existing product:

fetch("https://api-v1.kenzap.cloud/", {
  method: "post",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer your_api_key"
  },
  body: JSON.stringify({
      query: {
          product: {
              type:   "create",
              key:    "ecommerce-product",
              id:     "00232c6e9024c0d8d064af7754e1c60580fe4407",
              data:   "data": {
                                "title":        "Okinawa Sushi",
                                "description":  "A set of 7 pieces, comes with free ocha.",
                                "status":       "published".
                                "price":        "25.40"
                              }
          }
      }
  })
})
.then(response => response.json())
.then(response => {

  console.log(response);

})

Updates existing E-commerce product with the following values:

• Okinawa Sushi for title.
• A set of 7 pieces, comes with free ocha for description.
• published for status.
• 25.40 for price.

Delete

This type of query permanently deletes Kenzap Cloud stored record. It is mandatory to provide a 40-character record ID.

Delete Parameters

"query": {
    "record": {
        "type":       "delete",
        "key":        key,
        "id":         id
    }
}

The table below demonstrates various parameters that you can use to customize your find query.

Delete key

"key": "ecommerce-product"

This parameter specifies which extension data to query within the Cloud Space. Key names are arbitrary, meaning that each extension, has its own set of available keys. Think of keys as tables in the context of relational databases.

For example, E-commerce extension keys:

• ecommerce-product
• ecommerce-settings
• ecommerce-order

MyTicket extension keys:

• myticket-settings
• myticket-layouts
  

Delete id

"id": "e3de841f54b88997f2e18cfd60dd06ebb956db22"

You can query individual records by their unique ID. IDs are generated by the Cloud when a data record is first inserted into the database. ID example:

e3de841f54b88997f2e18cfd60dd06ebb956db22

Delete Examples

Delete existing product

The example in the right pane demonstrates how to permanently remove a product from the Kenzap Cloud.

Delete existing product:

fetch("https://api-v1.kenzap.cloud/", {
  method: "post",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer your_api_key"
  },
  body: JSON.stringify({
      query: {
          product: {
              type:   "delete",
              key:    "ecommerce-product",
              id:     "00232c6e9024c0d8d064af7754e1c60580fe4407"
          }
      }
  })
})
.then(response => response.json())
.then(response => {

  console.log(response);

})

Errors

The Kenzap API uses the following error codes: