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.
Prerequisites
- 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
Adopt a versioned naming convention for backend workflows
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.
Create a new version when making breaking changes
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.
Add deprecation tracking with a data model
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.
Build a router workflow for cleaner URL paths
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.
Communicate API changes to consumers
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 working example
1API VERSIONING — WORKFLOW SUMMARY2==================================34NAMING CONVENTION:5 v[version]-[action]-[resource]6 Examples: v1-get-users, v1-create-order, v2-get-users7 URL: /api/1.1/wf/v1-get-users89DATA TYPES:10 API_Version:11 Version (text), Status (Option Set: Active/Deprecated/Retired),12 Sunset_Date (date), Changelog (text), Created_Date (date)1314 API_Changelog:15 Version (text), Date (date),16 Change_Type (Option Set: Added/Changed/Deprecated/Removed),17 Description (text)1819 API_Consumer:20 Name (text), Email (text), API_Key (text),21 Versions_Used (list of text)2223BACKEND WORKFLOW: api-router24 Parameters: version (text), action (text), [payload params]25 1. Search API_Version where Version = version param26 2. Only when Status = Retired → Return error 'Version retired'27 3. Only when Status = Deprecated → Include sunset warning in response28 4. Route to correct workflow based on version + action2930DEPRECATION PROCESS:31 1. Create new version (v2) with breaking changes32 2. Set v1 Status to Deprecated, Sunset_Date = +90 days33 3. Email API consumers with migration guide34 4. Add changelog entry35 5. After sunset date: set v1 Status to Retired36 6. Retired endpoints return error response3738BREAKING vs NON-BREAKING:39 Breaking (new version required):40 - Remove/rename parameter41 - Change response structure42 - Alter existing behavior43 Non-breaking (update current version):44 - Add optional parameter45 - Add new response field46 - Fix bug without changing interfaceCommon mistakes when versioning API endpoints in Bubble.io: Step-by-Step Guide
Why it's a problem: Making breaking changes to an existing endpoint without creating a new version
How to avoid: Always create a new versioned endpoint for breaking changes and run both versions in parallel.
Why it's a problem: Not setting a sunset date for deprecated versions
How to avoid: Set a sunset date (typically 90 days) when deprecating and communicate it clearly to all consumers.
Why it's a problem: Retiring an API version without checking if anyone still uses it
How to avoid: 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
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I have a Bubble.io app that exposes backend workflows as API endpoints. External services depend on these endpoints. How should I implement API versioning to make changes without breaking their integrations?
Help me create a versioned API system. I need a backend workflow router that accepts version and action parameters, routes to the correct internal workflow, and returns a deprecation warning for old versions.
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.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation