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
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
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
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
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
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
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
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
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
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
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"
- The block evaluates the
-
Property Navigation:
- The
ref_property
specifies which property path to update within the selected objects - If empty, the entire object is considered for update
- The
-
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
- If the property is an array,
-
Value Modification:
set
: Directly replaces the value of the specified propertyadd
: 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
- If
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
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
Related Documentation
- Routes - Managing routes in Kinesis API
- Collections - Working with data collections
- Data - Working with data in Kinesis API