# How to version API endpoints in Bubble.io: Step-by-Step Guide

- Tool: Bubble
- Difficulty: Intermediate
- Time required: 20-25 min
- Compatibility: All Bubble plans
- Last updated: March 2026

## TL;DR

When external consumers depend on your Bubble API, breaking changes can take down their integrations. This tutorial shows how to manage API versioning in Bubble by creating versioned backend workflow endpoints, implementing a deprecation strategy, and communicating changes to API consumers — all without disrupting existing integrations.

## Overview: Versioning API Endpoints in Bubble

If external apps or services call your Bubble backend workflows, you need a versioning strategy to make changes without breaking existing consumers. This tutorial covers creating versioned endpoints, running multiple versions in parallel, deprecating old versions gracefully, and documenting changes for your API consumers.

## Before you start

- A Bubble app with backend workflows exposed as public API endpoints
- At least one external service consuming your API
- Understanding of backend workflows and the Workflow API

## Step-by-step guide

### 1. Adopt a versioned naming convention for backend workflows

When creating backend workflows that serve as API endpoints, include the version in the name. Instead of 'get-users', name it 'v1-get-users'. This creates the endpoint URL: https://yourapp.bubbleapps.io/api/1.1/wf/v1-get-users. When you need to make breaking changes, create 'v2-get-users' with the new schema while keeping v1 running. Both endpoints work simultaneously. Establish this convention from the start — even your first version should be v1.

> Pro tip: Create a naming standard document: v[version]-[action]-[resource]. Examples: v1-get-users, v1-create-order, v2-get-users.

**Expected result:** All API endpoints follow a versioned naming convention that supports running multiple versions in parallel.

### 2. Create a new version when making breaking changes

A breaking change is anything that removes or renames a parameter, changes the response structure, or alters existing behavior. When you need to make a breaking change: (1) Keep the existing v1 workflow untouched. (2) Create a new backend workflow with the v2 prefix. (3) Implement the new logic in v2. (4) Both v1 and v2 are now live simultaneously. Non-breaking changes (adding optional parameters, adding new response fields) can be made to the current version without creating a new one.

**Expected result:** A new API version is live alongside the old version, giving consumers time to migrate.

### 3. Add deprecation tracking with a data model

Create a Data Type called API_Version with fields: Version (text, e.g., 'v1'), Status (Option Set: Active, Deprecated, Retired), Sunset_Date (date), Changelog (text), and Created_Date (date). Create records for each active version. When deprecating, change Status to Deprecated and set a Sunset_Date (typically 90 days out). Build an admin page showing all versions with their statuses. On the v1 workflow, add a response header or field indicating deprecation: include a 'deprecated' field set to true and 'sunset_date' with the date.

**Expected result:** A tracked deprecation system with sunset dates and status tracking for all API versions.

### 4. Build a router workflow for cleaner URL paths

Instead of exposing many versioned endpoints, create a single entry-point backend workflow called 'api-router' that accepts a version parameter and action parameter. In the workflow, use conditions to route to the correct internal custom event or nested workflow. For example: Only when version = 'v1' AND action = 'get-users' → Trigger custom event v1-get-users. This gives consumers a cleaner URL structure: /api/1.1/wf/api-router?version=v1&action=get-users. The router can also handle deprecation warnings by checking the version's status before routing.

> Pro tip: For large APIs with many endpoints and versions, RapidDev can help architect a robust routing and versioning system with automated deprecation enforcement and consumer notification.

**Expected result:** A single API router endpoint handles version routing and deprecation checks centrally.

### 5. Communicate API changes to consumers

Create a public changelog page in your Bubble app that lists all API versions, changes, and deprecation notices. Use a Data Type called API_Changelog with fields: Version, Date, Change_Type (Option Set: Added, Changed, Deprecated, Removed), and Description. Display entries in a Repeating Group sorted by date descending. Include the changelog URL in your API documentation. When deprecating a version, send emails to registered API consumers (store their contact in an API_Consumer Data Type) notifying them of the sunset date and migration instructions.

**Expected result:** API consumers can view a changelog and receive notifications about deprecations and breaking changes.

## Complete code example

File: `Workflow summary`

```text
API VERSIONING — WORKFLOW SUMMARY
==================================

NAMING CONVENTION:
  v[version]-[action]-[resource]
  Examples: v1-get-users, v1-create-order, v2-get-users
  URL: /api/1.1/wf/v1-get-users

DATA TYPES:
  API_Version:
    Version (text), Status (Option Set: Active/Deprecated/Retired),
    Sunset_Date (date), Changelog (text), Created_Date (date)

  API_Changelog:
    Version (text), Date (date),
    Change_Type (Option Set: Added/Changed/Deprecated/Removed),
    Description (text)

  API_Consumer:
    Name (text), Email (text), API_Key (text),
    Versions_Used (list of text)

BACKEND WORKFLOW: api-router
  Parameters: version (text), action (text), [payload params]
  1. Search API_Version where Version = version param
  2. Only when Status = Retired → Return error 'Version retired'
  3. Only when Status = Deprecated → Include sunset warning in response
  4. Route to correct workflow based on version + action

DEPRECATION PROCESS:
  1. Create new version (v2) with breaking changes
  2. Set v1 Status to Deprecated, Sunset_Date = +90 days
  3. Email API consumers with migration guide
  4. Add changelog entry
  5. After sunset date: set v1 Status to Retired
  6. Retired endpoints return error response

BREAKING vs NON-BREAKING:
  Breaking (new version required):
    - Remove/rename parameter
    - Change response structure
    - Alter existing behavior
  Non-breaking (update current version):
    - Add optional parameter
    - Add new response field
    - Fix bug without changing interface
```

## Common mistakes

- **Making breaking changes to an existing endpoint without creating a new version** — External consumers' integrations break immediately with no warning or migration path. Fix: Always create a new versioned endpoint for breaking changes and run both versions in parallel.
- **Not setting a sunset date for deprecated versions** — Without a deadline, consumers have no incentive to migrate, and you end up maintaining old versions indefinitely. Fix: Set a sunset date (typically 90 days) when deprecating and communicate it clearly to all consumers.
- **Retiring an API version without checking if anyone still uses it** — Active consumers lose their integration without warning, damaging trust and potentially their business. Fix: Log API calls per version and check usage before retiring. Email remaining consumers with a final warning.

## Best practices

- Include version numbers in endpoint names from the very first version (start with v1)
- Run deprecated versions for at least 90 days before retiring them
- Add deprecation notices in API responses when a version is deprecated
- Maintain a public changelog accessible to all API consumers
- Log API call volume per version to track migration progress
- Email consumers when their used version enters deprecation
- Distinguish between breaking and non-breaking changes to avoid unnecessary version bumps

## Frequently asked questions

### Does Bubble have built-in API versioning?

No. Bubble's API uses a fixed version (1.1) in the URL path. You need to implement your own versioning through workflow naming conventions or a router pattern.

### How long should I keep deprecated API versions running?

Industry standard is 90 days minimum. For enterprise consumers, 6-12 months is common. Check usage logs — if no one is calling the deprecated version, you can retire it sooner.

### What counts as a breaking change?

Removing or renaming a parameter, changing the response structure, changing a field's data type, or altering existing behavior. Adding optional parameters or new response fields is non-breaking.

### Can I use URL path versioning like /api/v1/ and /api/v2/?

Bubble's URL structure is fixed at /api/1.1/wf/. You cannot customize the path structure. Use the workflow name (v1-get-users, v2-get-users) or a version query parameter instead.

### How do I track which consumers use which API version?

Log every API call to a database record with the version, consumer identifier (from their API key), and timestamp. Build a dashboard showing call volume per version per consumer.

### Can RapidDev help design an API versioning strategy?

Yes. RapidDev can architect a complete API management system including versioning, documentation, consumer management, usage tracking, and automated deprecation enforcement.

---

Source: https://www.rapidevelopers.com/bubble-tutorial/version-api-endpoints-bubble
© RapidDev — https://www.rapidevelopers.com/bubble-tutorial/version-api-endpoints-bubble