Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Using Loops to Filter Data

This tutorial will guide you through using loops in Kinesis API to filter a list of data. You'll create an API endpoint that fetches a list of creatures and returns only the ones that match a specific criterion passed in the URL. This is a great way to learn how to build more dynamic and powerful API logic.

Prefer video tutorials? You can follow along with our YouTube walkthrough of this same project.

Prerequisites

Before you begin, you need:

  1. Access to a Kinesis API instance:
  2. A user account with ADMIN or ROOT privileges
  3. Basic understanding of REST APIs and the Flow Editor

1. Creating a Project

First, let's create a project for our creatures API:

  1. Log in to your Kinesis API instance
  2. Navigate to the Projects page from the main menu
  3. Click "Create a new project" to open the project creation modal
  4. Fill in the following details:
    • Name: "Creatures"
    • ID: "creatures"
    • Description: "To have fun with some beings." (or anything else you want)
    • API Path: "/creatures" (this will be the base URL path for all routes in this project) Create Project
  5. Click "Create" to save your project

2. Creating a Collection

Next, we'll create a collection to store our creature data:

  1. From your newly created project page, click "Create New" on the "Collections" section
  2. Fill in the following details:
    • Name: "Creatures"
    • ID: "creatures"
    • Description: "To store details on every creature." (or anything else you want) Create Collection
  3. Click "Create" to save your collection

Project Page

3. Creating Structures

Now we'll create some structures (fields) to store our creature value:

  1. From the "Creatures" collection page, locate the "Structures" section
  2. Click "Create New" to add a structure
  3. Fill in the following details:
    • Name: "Species"
    • ID: "species"
    • Description: "" (leave blank or insert anything else)
    • Type: "TEXT"
    • Required: Check this box
    • Unique: Check this box Create Species Structure
  4. Click "Create" to save the structure
  5. Click "Create New" to add another structure
  6. Fill in the following details:
    • Name: "Is a pet"
    • ID: "is_pet"
    • Description: "Whether the species is considered as a pet." (leave blank or insert anything else)
    • Type: "BOOLEAN"
    • Required: Check this box Create Is Pet Structure
  7. Click "Create" to save the structure

Collection Page

4. Creating Data

Now we'll create some initial data objects for our creatures:

  1. Navigate to the "Data" section in the top navigation bar
  2. Select your project and then the "Creatures" collection
  3. Click "Create New" to create a data object
  4. Add a nickname (optional)
  5. For the "species" field, enter: "Dog"
  6. For the "is a pet" field, check the checkbox Create Data
  7. Click "Create" to save your data object
  8. Repeat the above steps as many times as you want for different species and whether they are typically considered to be pets
  9. Those are the data objects that have been created as example for this tutorial:
    • Creature 1:
      • species: "Dog"
      • is_pet: true
    • Creature 2:
      • species: "Cat"
      • is_pet: true
    • Creature 3:
      • species: "Scorpion"
      • is_pet: false
    • Creature 4:
      • species: "Kangaroo"
      • is_pet: false
    • Creature 5:
      • species: "Hamster"
      • is_pet: true

Data Page

5. Creating a Route

Now, we'll create a route that filters these creatures based on whether they are a pet:

  1. Navigate to Routes in the top navigation bar
  2. Select your project
  3. Click "Create New" to create a route
  4. Fill in the route details:
    • Route ID: "fetch_creatures"
    • Route Path: "/fetch"
    • HTTP Method: "GET"
  5. In the URL Parameters section, set the delimiter to be "&", then click "Add" and define a parameter:
    • ID: "pet"
    • Type: "BOOLEAN"
  6. The "JWT Authentication" and "Body" sections don't need to be modified Create Route

Building the Route Logic in the Flow Editor

The Flow Editor is where we define what happens when our route is called. We'll build a flow that fetches all creatures, loops through them, and returns only the ones that match the pet URL parameter.

Follow these steps:

  1. Add a FETCH block:

    • Drag a FETCH block onto the canvas and connect the START node to it
    • Fill in the following details:
      • Local Name: "_allCreatures"
      • Reference Collection: "creatures"

    Fetch Block

  2. Add a PROPERTY block:

    • Drag a PROPERTY block onto the canvas and connect the FETCH block to it
    • Fill in the following details:
      • Local Name: "_allCreaturesLength"
      • Property Apply: "LENGTH"
    • As for the data section, fill in the following details:
      • Reference: Check this box
      • Type: "Array"
      • Data: "_allCreatures"

    Property Block

  3. Add an ASSIGNMENT block:

    • Drag an ASSIGNMENT block onto the canvas and connect the PROPERTY block to it
    • Fill in the following details:
      • Local Name: "_foundCreatures"
    • Add an "operation" submodule with 1 operand, and fill in the following details:
      • Reference: Leave unchecked
      • Type: "Array"
      • Data: ""
    • Operation Type: "None"

    Assignment Block

  4. Add a LOOP block:

    • Drag a LOOP block onto the canvas and connect the ASSIGNMENT block to it
    • Fill in the following details:
      • Local Name: "index"
    • Fill in the following details for the start section:
      • Reference: Leave unchecked
      • Type: "Integer"
      • Data: "0"
    • Fill in the following details for the end section:
      • Reference: Check this box
      • Type: "Integer"
      • Data: "_allCreaturesLength"
    • Leave everything else as it is

    Loop Block

  5. Add a PROPERTY block:

    • Drag a PROPERTY block onto the canvas and connect the previous LOOP block to it
    • Fill in the following details:
      • Local Name: "_creature"
      • Property Apply: "GET_INDEX"
      • Additional: "index"
    • As for the data section, fill in the following details:
      • Reference: Check this box
      • Type: "Array"
      • Data: "_allCreatures"

    Property Block

  6. Add another PROPERTY block:

    • Drag another PROPERTY block onto the canvas and connect the previous PROPERTY block to it
    • Fill in the following details:
      • Local Name: "_species"
      • Property Apply: "GET_PROPERTY"
      • Additional: "species"
    • As for the data section, fill in the following details:
      • Reference: Check this box
      • Type: "Other"
      • Data: "_creature"

    Property Block

  7. Add another PROPERTY block:

    • Drag another PROPERTY block onto the canvas and connect the previous PROPERTY block to it
    • Fill in the following details:
      • Local Name: "_is_pet"
      • Property Apply: "GET_PROPERTY"
      • Additional: "is_pet"
    • As for the data section, fill in the following details:
      • Reference: Check this box
      • Type: "Other"
      • Data: "_creature"

    Property Block

  8. Add an ASSIGNMENT block:

    • Drag an ASSIGNMENT block onto the canvas and connect the PROPERTY block to it
    • Fill in the following details:
      • Local Name: "_foundCreatures"
    • Add a "condition" submodule with 2 operands, and fill in the following details:
      • First Operand:
        • Reference: Check this box
        • Type: "Boolean"
        • Data: "_is_pet"
      • Second Operand:
        • Reference: Check this box
        • Type: "Boolean"
        • Data: "pet"
    • Condition Type: "Equal To"
    • Add an "operation" submodule with 2 operands, and fill in the following details:
      • First Operand:
        • Reference: Check this box
        • Type: "Array"
        • Data: "_foundCreatures"
      • Second Operand:
        • Reference: Check this box
        • Type: "Array"
        • Data: "_species"
    • Operation Type: "Addition"

    Assignment Block

  9. Add an END_LOOP block:

    • Drag an END_LOOP block onto the canvas and connect the ASSIGNMENT block to it
    • Fill in the following details:
      • Local Name: "index"

    End Loop Block

  10. Add a RETURN block:

    • Drag a RETURN block onto the canvas and connect the END_LOOP block to it
    • Add an "object pair" submodule
    • Fill in the following details:
      • id: "creatures"
      • data:
        • Reference: Check this box
        • Type: "Array"
        • Data: "_foundCreatures"

    Return Block

  11. Ensure that your Flow Editor looks like the following: Flow Editor

  12. Click "Create" to save your route

Route Page

6. Testing via Playground

Now let's test our creatures API:

  1. Navigate to Playground in the top navigation bar
  2. Select your project
  3. Click on the "FETCH_CREATURES" route Playground Project Page
  4. Enter the value "true" for the "pet" field in the "URL Parameters" section
  5. Click "Send" to make a request to your API
  6. You should see a response like: 
    {
  "creatures": ["dog", "cat", "hamster"]
}
  7. Enter the value "false" for the "pet" field in the "URL Parameters" section
  8. Click "Send" again
  9. You should see a response like: 
    {
  "creatures": ["scorpion", "kangaroo"]
}

Playground Request Page

Congratulations!

You've successfully built an API that uses a loop to filter data based on user input. You have learned how to:

  • Fetch a list of data objects
  • Create an empty array to store results
  • Loop through a data list
  • Use conditional logic within a loop
  • Add items to an array dynamically
  • Return the filtered results

Next Steps

Challenge yourself by extending this project:

  • Add more structures: Add a diet (e.g., "carnivore", "herbivore") or habitat structure to your collection
  • More complex filtering: Modify the route to accept multiple filter parameters (e.g., pet and diet)
  • Implement sorting: After filtering, use another loop or a different block to sort the results alphabetically by species

Continuous Improvement

Note: Kinesis API is continuously evolving based on user feedback. As users test and provide suggestions, the platform will become simpler, more intuitive, and easier to use. This tutorial will be updated regularly to reflect improvements in the user experience and new features.

We value your feedback! If you have suggestions for improving this tutorial or the Kinesis API platform, please reach out through our contact page or consider raising a new ticket.