Articles in this section

Branching in API builder

Kathyana Queeman
Updated

Note

This article covers branching in the API builder. To use branching in the Flow Builder, see Apply branching to your flow.

In API Builder, you can add branching to your APIs to simplify condition-based routing and reduce complexity when working with multiple applications or endpoints. Instead of building multiple APIs, you can route request data into different branches based on parameters, execute distinct logic in each path, and consolidate the final response. Branching decreases your effort to build an API, which involves complicated steps and multiple applications or endpoints.

Get_a_pet_API_builder.png

Let's say you want to send the pet data in an API request through multiple lookups and imports. With branching, you are no longer restricted to a linear API; instead, you can plan and create an API with many branchings to solve your business problems.

Note

The only branching type available in the API Builder is the First matching branch. You can add a maximum of 25 branches (indicated by router icons) in an API and a maximum of 25 branches (indicated by dotted lines) in a single branching.

Response picker

You can use the Response picker, an out-of-the-box branching router, to define multiple response nodes that seamlessly handle different response codes and structures.

The backend sets a true or false boolean flag called Success to indicate whether the API succeeded. This flag cannot be edited; however, you can configure your API's behavior using the Response picker to set record flow conditions. You don't have to use the flag to determine whether the API succeeded, but we recommend it.

Two branches are automatically configured: The Success response executes when the Success flag is true, and the Error response executes when the Success flag is false.

For example, if the Success flag in the backend is true, the Success response branch's record flow conditions say that the API should return a successful API response. You can see this in the screenshot below; if Success equals true, the Success response branch will execute.

You can edit how the Success response and Error response branches execute by editing the record flow conditions. For example, if you'd like to return a response based on a specific error or a test mode response instead of the Success boolean flag. Don't forget you can add more responses and specify their record flow conditions.

response_picker_window.png

There are some rules and requirements to be aware of when using the Response picker:

  • The Response picker is added by default, and its name cannot be updated.

  • There are always two default branches that lead to Success and Error response nodes, which cannot be removed.

  • The Response picker's default names are "Success response" and "Error response;" however, you can rename them. If you add another response node, the name will be blank by default.

  • You can add new branches, which will automatically add new response nodes.

View your branches

Different view icons are available in the lower-left corner of the API builder. You can click an option/icon based on how you want to view your API branching at any time.

branching_views.png

Select view options

The API builder supports scrolling so you can move through your API horizontally and vertically. This is useful for viewing large or complicated APIs with branching.

After you add a branch, you can see the branching router (Icon_Branching_New.svg​​) icon. You can click this icon to edit the branching at any time. Each dotted line represents a branch. The branch name (for example, Branch 1.0) is shown above the first step, but it represents the dotted line. A branch could include several step bubbles based on the workflow but must always end in a response bubble.

You can quickly reorder steps by dragging and dropping them to a different location in your API. This option can be useful while planning, designing, or testing your API. All associated tools, such as mappings, move along with the step, preserving your configurations. It's a good practice to check and update your configuration if required after you've reordered any step.

Branching type: First matching branch

In this branching type, the order of branches is vital because records are matched with the branch conditions sequentially based on the branch index (the order of branches). A record flows through only the first matching branch.

This example shows that request records flow through the first matching branch based on the request type. In a "Get a pet" API, you might be able to get different pets, such as a dog, a cat, or a fish.

  • Records that match "Get a dog" flow through the "Get Dog" branch.

  • Records that match "Get a cat" flow through the "Get cat" branch.

  • Records that match "Get a fish" flow through the "Get fish" branch.

Records flow through the first matching branch and can be further processed based on the workflow.

Add branching

You can add branching to an API to send the data down different paths for further processing.

Tip

You can easily reorder steps by dragging and dropping them to a different location in your API. This option can be useful while planning, designing, or testing your API. All associated tools, such as mappings and filters, move along with the step, preserving your configurations. It's a good practice to check and update your configuration if required after you've reordered any step.

You must name the branching and configure these components when you add branching.

Components

Configure…

Branching type

How records must match conditions in all the branches, that is, sequentially.

Branches

The conditions that records must match in each branch to flow through. (You must also provide a suitable name and description for each branch.)

  1. Click Tools → API builder to create a new API.

    –OR–

    Click Resources → APIs → API builder → <Your API> to navigate to a specific API.

  2. In Destination & Lookups, click the plus sign (+) next to a step. From the list, select Add branching.

  3. In the Add branching window, enter a name for your branch. You can provide a name that indicates what the branching represents or does in the API. For example, "get a dog" or "update a pet" branching. If your branching name is long, it's shown partially in the API builder, but you can see the full name if you hover over it.

    branching_name.png

  4. Branching type: The only option available is First matching branch.

  5. Branches: Two branches are automatically included in the Add branching window with default names Branch X.0 and Branch X.1

  6. Edit the default name and description for the branches.

    edit_branch_name_desc.png

  7. If you want to add another branch, click + Add branch and configure details. (You can also reorder or delete branches.)

    add_branch.png

  8. Configure conditions in each branch using either Rules or JavaScript.

  9. Click Preview to check if you have the required results.

    • Input – Preview the input data/record for branching.

    function_input.png

    • Output – Preview the branch index and name into which the record will move, that is, the first branch that matches.

    function_output.png

  10. Click Save and close.

Configure branch conditions using Rules

By default, the Rules format is selected in the right corner to add conditions. You can add rules in a branch based on the conditional and logical operators provided. Only records that match the filter conditions flow through a branch.

Note

Branching does not support array-type fields. You must transform your data before using it in branching rules. For more information, see "Branches & array data" in Apply branching to a flow.

You can also add condition groups if required. Groups allow you to segment your filtration logic for complex circumstances if you have a set of rules that use multiple Boolean conditions. For example, you could create one condition group that uses the NOT Boolean operator to exclude records that were created before a certain date, then create another condition group to include records that use the AND or OR operator.

You can collapse and expand conditions by clicking the arrow icon next to the branch name. By default, the conditions are shown in the expanded format.

  1. Add conditions using the conditional and logic operators provided in the Filter editor.

    filter_rule-1.png

  2. If required, click Add condition to include another condition.

  3. If required, click Add conditions group to combine conditions.

  4. Click Preview and check your output, then click Save and Close.

Configure branch conditions using JavaScript

We recommend creating a script that includes a branching function first. Then, you can select it and edit the details in the Branch conditions script section as required.

After you have created a script:

  1. In the upper-right corner, select JavaScript.

  2. In the Branch conditions scripts section,

    1. Under Scripts, select an existing script that includes a branching function. When you select the script, it shows in the Script editor.

    2. Under Function, select branching if it is not already selected.

  3. If required, in the Edit branching window, you can edit the branching name.

  4. Click Preview and check your function output, then click Save and Close.

Order your branches

The order of branches is vital because records are matched with the branch conditions sequentially based on the branch index (the order of branches). A request flows through only the first matching branch.

The Response picker cannot be deleted, as at least two branches should be connected to responses. The Delete branch option is disabled automatically if you try to delete the only two remaining branches connecting the request to the response. If there are dangling branches or the Response step is not configured, the API will return a 501 - Not Implemented response code.

For example, you might want to create an API request to add one pet's veterinary data to a database of pets in one store. In this case, you must create multiple branches that lead to different API responses.

  • Requests that are successful flow to the Success branch.

  • Bad requests (not enough data) flow to the Bad request branch.

  • Requests with an invalid API Token flow to the 401 Unauthorized branch.

  • Requests with duplicate information (e.g., previously existing microchip IDs) flow to the 409 Conflict branch.

The example below illustrates every aspect of creating an API. In this case, every API response equals one branch node. So, this API would contain four branches (one for every response).

Create a new pet

This request creates a new pet using the relative URI: /stores/:storeId/pets/. It includes one request, one import, four branches, and four responses. Each branch ends in a different response node.

Note

In this example, the API request data and the API response data are identical. In practice, the API request data may include different or additional fields. This is where mapping helps.

API request body

  • Uses POST /stores/123/pets/ to create a new pet in store ID 123.

  • Includes detailed pet information such as microchip ID, breed information, and medical history.

{
  "name": "Buddy",
  "age": 3,
  "breed": "Labrador Retriever",
  "weight_kg": 28.5,
  "microchip_id": "982000411234567",
  "owner": {
    "id": 1001,
    "name": "John Doe",
    "phone": "+1-555-1234"
  },
  "last_visit": "2024-01-15",
  "vaccinations": ["Rabies", "Distemper", "Parvovirus"],
  "medical_history": [
    {
      "date": "2023-06-10",
      "condition": "Ear infection",
      "treatment": "Antibiotics"
    },
    {
      "date": "2022-09-05",
      "condition": "Allergic reaction",
      "treatment": "Antihistamines"
    }
  ],
  "dietary_preferences": {
    "food_brand": "Hill’s Science Diet",
    "meal_frequency": 2,
    "allergies": ["Chicken", "Soy"]
  },
  "exercise_routine": {
    "daily_walks": 2,
    "walk_duration_minutes": 30,
    "favorite_activity": "Fetch"
  }
}

Import: Create a new pet

An import step allows you to take the request data provided above and send it to your database, thus adding the pet to the database. In this import step, you'll want to configure the import and response mapping so the data your API consumer sends is properly mapped to your database.

API response: Successful Pet Creation

This is one branch ending in a successful pet creation. You'll want to add API response schema mapping here to include the unique ID and any other data you'd like to include in your response.

  • 201 Created → Indicates successful creation.

  • Includes a unique ID (101) for the newly created pet.

  • Returns a timestamp (created_at) to confirm when the record was created.

{
  "status": "success",
  "message": "Pet record created successfully.",
  "data": {
    "id": 201,
    "name": "Buddy",
    "age": 3,
    "breed": "Labrador Retriever",
    "weight_kg": 28.5,
    "microchip_id": "982000411234567",
    "store": {
      "id": 123,
      "name": "Happy Paws Veterinary Clinic",
      "location": "123 Main St, Springfield, IL"
    },
    "owner": {
      "id": 1001,
      "name": "John Doe",
      "phone": "+1-555-1234"
    },
    "last_visit": "2024-01-15",
    "vaccinations": ["Rabies", "Distemper", "Parvovirus"],
    "medical_history": [
      {
        "date": "2023-06-10",
        "condition": "Ear infection",
        "treatment": "Antibiotics"
      },
      {
        "date": "2022-09-05",
        "condition": "Allergic reaction",
        "treatment": "Antihistamines"
      }
    ],
    "dietary_preferences": {
      "food_brand": "Hill’s Science Diet",
      "meal_frequency": 2,
      "allergies": ["Chicken", "Soy"]
    },
    "exercise_routine": {
      "daily_walks": 2,
      "walk_duration_minutes": 30,
      "favorite_activity": "Fetch"
    },
    "created_at": "2025-02-10T14:30:00Z"
  }
}

API response: Bad Request (Missing Required Fields)

This is one branch ending in a "bad request" response.

{
  "status": "error",
  "message": "Missing required fields: name, breed"
}

API response: 401 Unauthorized (Invalid API Token)

This is one branch ending in an "unauthorized" response.

{
  "status": "error",
  "message": "Unauthorized. Invalid API token."
}

API response: 409 Conflict (Duplicate Microchip ID)

This is one branch ending in a "conflict" response.

{
  "status": "error",
  "message": "A pet with this microchip ID already exists."
}