Blocks

Blocks are the building components of Kinesis API's X Routing system. Each block represents a specific operation that can be connected together to form a complete route logic. This guide explains how to use each block type and its configuration options.

Overview

The X Routing system uses a visual flow-based approach where you connect different blocks to process requests, manipulate data, and return responses. Each block has specific inputs, outputs, and configuration options.

Common Block Properties

All blocks share some common properties:

Connections: Each block (except START) has an input connector and an output connector
Expansion: Click the header to expand/collapse a block's configuration panel
Deletion: Click the X button to delete a block (not available for START block)

Block Types

START Block

The START block is the entry point of every route flow. It is automatically created and cannot be deleted.

Purpose: Indicates where the request processing begins
Configuration: None required
Connections: Can only connect to one block via its output

FETCH Block

Fetch Block

The FETCH block retrieves data from a collection and stores it in a local variable.

Purpose: Retrieve data from collections
Configuration:
- Local Name: Variable name to store the fetched data
- Reference Collection: Name of the collection to fetch data from
Usage: Use FETCH to retrieve data that you'll need later in your route processing
Example: Fetching user data to validate permissions

{
  "local_name": "users",
  "ref_col": "users_collection"
}

ASSIGNMENT Block

Assignment Block

The ASSIGNMENT block assigns a value to a variable based on conditions and operations.

Purpose: Create or modify variables
Configuration:
- Local Name: Variable name to store the result
- Conditions: Optional conditions to evaluate
- Operations: Operations to perform if conditions are met
Usage: Use for variable creation, data transformation, or conditional assignments
Example: Creating a status variable based on user role

{
  "local_name": "isAdmin",
  "conditions": [
    {
      "operands": [
        {
          "ref_var": true,
          "rtype": "STRING",
          "data": "role"
        },
        {
          "ref_var": false,
          "rtype": "STRING",
          "data": "admin"
        }
      ],
      "condition_type": "EQUAL_TO",
      "not": false,
      "next": "NONE"
    }
  ],
  "operations": [
    {
      "operands": [
        {
          "ref_var": false,
          "rtype": "BOOLEAN",
          "data": "true"
        }
      ],
      "operation_type": "NONE",
      "not": false,
      "next": "NONE"
    }
  ]
}

TEMPLATE Block

Template Block

The TEMPLATE block creates a string using a template with variable substitution.

Purpose: Create dynamic strings by combining static text and variable values
Configuration:
- Local Name: Variable name to store the templated string
- Template: The template string with placeholders
- Data: Variables to use in the template
- Conditions: Optional conditions for template processing
Usage: Use for creating dynamic messages, formatted content, or SQL queries
Example: Creating a personalized greeting

{
  "local_name": "greeting",
  "template": "Hello, {}! Welcome to {}.",
  "data": [
    {
      "ref_var": true,
      "rtype": "STRING",
      "data": "user.name"
    },
    {
      "ref_var": false,
      "rtype": "STRING",
      "data": "Kinesis API"
    }
  ],
  "conditions": []
}

CONDITION Block

Condition Block

The CONDITION block evaluates logical conditions and controls flow based on the result.

Purpose: Implement conditional logic and flow control
Configuration:
- Conditions: Set of conditions to evaluate
- Action: What to do if conditions are met (CONTINUE, BREAK, FAIL)
- Fail Object: Status and message to return if action is FAIL
Usage: Use for validation, permission checks, or branching logic
Example: Validating user permissions

{
  "conditions": [
    {
      "operands": [
        {
          "ref_var": true,
          "rtype": "STRING",
          "data": "user.role"
        },
        {
          "ref_var": false,
          "rtype": "STRING",
          "data": "admin"
        }
      ],
      "condition_type": "NOT_EQUAL_TO",
      "not": false,
      "next": "NONE"
    }
  ],
  "action": "FAIL",
  "fail": {
    "status": 403,
    "message": "Unauthorized: Insufficient permissions"
  }
}

LOOP Block

Loop Block

The LOOP block iterates over a range of values or an array.

Purpose: Process multiple items or iterate a specific number of times
Configuration:
- Local Name: Variable name for the current loop value
- Start: Starting value for the loop
- End: Ending value for the loop
- Step: Optional increment value (defaults to 1)
- Include Last: Whether to include the end value in the iteration
Usage: Use for batch processing, pagination, or iterative operations
Example: Processing a list of items

{
  "local_name": "index",
  "start": {
    "ref_var": false,
    "rtype": "INTEGER",
    "data": "0"
  },
  "end": {
    "ref_var": true,
    "rtype": "INTEGER",
    "data": "items.length"
  },
  "step": null,
  "include_last": false
}

END_LOOP Block

End Loop Block

The END_LOOP block marks the end of a loop section.

Purpose: Indicates where a loop section ends
Configuration:
- Local Name: Must match the corresponding LOOP block's local name
Usage: Must be paired with a LOOP block
Example: Closing a loop that processes items

{
  "local_name": "index"
}

Filter Block

The FILTER block filters items in an array based on specified criteria.

Purpose: Reduce an array to only items that match criteria
Configuration:
- Local Name: Variable name to store the filtered results
- Reference Variable: Variable containing the array to filter
- Reference Property: Optional property to filter by
- Filters: Filtering criteria
Usage: Use to find matching items or remove unwanted elements
Example: Filtering active users

{
  "local_name": "activeUsers",
  "ref_var": "users",
  "ref_property": "status",
  "filters": [
    {
      "operand": {
        "ref_var": false,
        "rtype": "STRING",
        "data": "active"
      },
      "operation_type": "EQUAL_TO",
      "not": false,
      "next": "NONE"
    }
  ]
}

PROPERTY Block

Property Block

The PROPERTY block accesses or manipulates properties of objects or arrays.

Purpose: Extract values from objects/arrays or perform operations on them
Configuration:
- Local Name: Variable name to store the result
- Data: The object or array to operate on
- Apply: Operation to apply (GET_PROPERTY, LENGTH, GET_FIRST, GET_LAST, GET_INDEX)
- Additional: Additional information for the operation (e.g., property name, index)
Usage: Use to extract specific data or compute properties of collections
Example: Getting an object's property

{
  "local_name": "userName",
  "property": {
    "data": {
      "ref_var": true,
      "rtype": "OTHER",
      "data": "user"
    },
    "apply": "GET_PROPERTY",
    "additional": "name"
  }
}

FUNCTION Block

Function Block

The FUNCTION block executes predefined functions.

Purpose: Perform common operations using built-in functions
Configuration:
- Local Name: Variable name to store the function result
- Function ID: The function to execute (e.g., V4, GENERATE_TIMESTAMP, GENERATE_JWT_TOKEN, PAGINATE)
- Parameters: Function parameters
Usage: Use for utility operations like generating IDs or formatting dates
Example: Generating a UUID

{
  "local_name": "newId",
  "func": {
    "id": "V4",
    "params": []
  }
}

OBJECT Block

Object Block

The OBJECT block creates a new object with specified key-value pairs.

Purpose: Construct custom objects
Configuration:
- Local Name: Variable name to store the created object
- Pairs: Key-value pairs for the object
Usage: Use to create response objects or structured data
Example: Creating a user profile object

{
  "local_name": "profile",
  "pairs": [
    {
      "id": "name",
      "data": {
        "ref_var": true,
        "rtype": "STRING",
        "data": "user.name"
      }
    },
    {
      "id": "email",
      "data": {
        "ref_var": true,
        "rtype": "STRING",
        "data": "user.email"
      }
    }
  ]
}

UPDATE Block

Update Block

The UPDATE block modifies existing data in a collection based on specified criteria and rules.

Purpose: Perform targeted updates to collection data
Configuration:
- Reference Collection: Collection containing the data to update
- Reference Property: Property path used to identify or navigate the data structure (can be empty or in the form 'field' or 'custom_structure.field')
- Add: Optional value to add (used for arrays or numeric additions)
- Set: Optional value to set (used for direct replacement of values)
- Filter: Used when the property is an array to filter which elements of the array should be updated
- Targets: Specifies which data objects to update by doing checks against the fields within them
- Save: Boolean indicating whether to persist changes immediately
- Conditions: Optional conditions that must be met for the update to proceed
Usage: Use for complex data updates, especially when you need to update specific fields conditionally or work with arrays
Example: Updating specific fields of user records that match certain criteria

{
  "ref_col": "users",
  "ref_property": "profile.settings",
  "add": null,
  "set": {
    "ref_var": true,
    "rtype": "OTHER",
    "data": "newSettings"
  },
  "filter": {
    "operand": {
      "ref_var": false,
      "rtype": "STRING",
      "data": "darkMode"
    },
    "operation_type": "EQUAL_TO",
    "not": false,
    "next": "NONE"
  },
  "targets": [
    {
      "field": "userId",
      "conditions": [
        {
          "operands": [
            {
              "ref_var": false,
              "rtype": "STRING",
              "data": "123"
            }
          ],
          "condition_type": "EQUAL_TO",
          "not": false,
          "next": "NONE"
        }
      ]
    }
  ],
  "save": true,
  "conditions": []
}

How the UPDATE Block Works:

Initial Conditions Check: The block first evaluates any conditions to determine if the update should proceed.
Target Selection:
- The block evaluates the targets to determine which data objects should be updated
- Each target specifies a field and conditions for selecting data objects
- For example, in the above JSON, it will select data objects where userId equals "123"
Property Navigation:
- The ref_property specifies which property path to update within the selected objects
- If empty, the entire object is considered for update
Filter Application:
- If the property is an array, filter determines which array elements to update
- For example, it might update only array elements where a certain property equals a certain value
Value Modification:
- set: Directly replaces the value of the specified property
- add: For arrays, adds elements; for numbers, performs addition operation
Persistence:
- If save is true, changes are immediately persisted to the database
- If false, changes remain in memory for further processing

CREATE Block

Create Block

The CREATE block creates new data in a collection.

Purpose: Insert new records into collections
Configuration:
- Reference Collection: Collection where data will be created
- Reference Object: Object containing the data to create
- Save: Whether to save immediately
- Conditions: Optional conditions for creation
Usage: Use to insert new records based on request data
Example: Creating a new user

{
  "ref_col": "users",
  "ref_object": "newUser",
  "save": true,
  "conditions": []
}

RETURN Block

Return Block

The RETURN block ends processing and returns a response to the client.

Purpose: Generate and send the API response
Configuration:
- Pairs: Key-value pairs for the response object
- Conditions: Optional conditions for the response
Usage: Use to complete the request and send data back to the client
Example: Returning a success response with data

{
  "pairs": [
    {
      "id": "status",
      "data": {
        "ref_var": false,
        "rtype": "INTEGER",
        "data": "200"
      }
    },
    {
      "id": "data",
      "data": {
        "ref_var": true,
        "rtype": "OTHER",
        "data": "result"
      }
    }
  ],
  "conditions": []
}

Best Practices

Start Simple: Begin with basic flows and add complexity as needed
Use Descriptive Names: Choose clear variable names for readability
Handle Errors: Include appropriate condition blocks to validate inputs and handle errors
Test Thoroughly: Test your routes with various inputs to ensure they work as expected
Document Your Logic: Add comments to your flows to explain complex logic

Routes - Managing routes in Kinesis API
Collections - Working with data collections
Data - Working with data in Kinesis API

Kinesis API Docs