Summary
This is an improvement proposal. If after review it is deemed unnecessary, this issue can be closed.
Problem
The Public API uses an inconsistent versioning scheme across its endpoints. Some endpoints have no version prefix, while others use v2 or v3, with no clear rationale:
No version prefix
GET /templatesGET /templates/<ID>POST /templates/<ID>/runGET /workflows/fieldsPOST /workflows/<ID>/task-completeGET /accounts/users
Version v2
GET /v2/tasks/<ID> — get a single task
Version v3
GET /v3/tasks — list tasks
Issues this creates
- Discoverability — a developer finding
/v2/tasks will naturally look for /v2/templates, /v2/workflows, etc., which do not exist
- Currency confusion — is
/templates the latest version? Is there a /v2/templates or /v3/templates that supersedes it? No way to know without reading source code
- API client design — building a versioned SDK (
client.v3.tasks.list()) becomes awkward when most endpoints have no version
- Future maintenance — when a breaking change is needed for
/templates, should it become /v2/templates or /v4/templates?
Root cause
Based on backend/src/urls.py, the versioning is historical:
/v3/tasks was added as a Zapier-specific endpoint (see # Using by Zapier comment in urls.py)/v2/tasks was an earlier iteration registered via the DRF router- Unversioned endpoints are the original API surface
Proposed Solutions
Option A — Unified version prefix (long-term):
Introduce a consistent prefix for all endpoints: /api/v1/templates, /api/v1/tasks, /api/v1/workflows, /api/v1/users. Maintain old endpoints as aliases during a deprecation period.
Option B — Version aliases (non-breaking):
Add aliases so all endpoints are accessible with a consistent prefix (e.g., /v3/templates → alias to /templates). Document /v3/ as the recommended prefix.
Option C — Documentation only (minimal):
Document the versioning situation clearly: unversioned endpoints = current stable API; /v2/ and /v3/ prefixes for tasks are legacy artifacts.
Expected Outcome
Developers can predict the URL pattern for any API resource without consulting documentation or source code. All endpoints follow a single, consistent versioning convention.
Summary
This is an improvement proposal. If after review it is deemed unnecessary, this issue can be closed.
Problem
The Public API uses an inconsistent versioning scheme across its endpoints. Some endpoints have no version prefix, while others use
v2orv3, with no clear rationale:No version prefix
GET /templatesGET /templates/<ID>POST /templates/<ID>/runGET /workflows/fieldsPOST /workflows/<ID>/task-completeGET /accounts/usersVersion v2
GET /v2/tasks/<ID>— get a single taskVersion v3
GET /v3/tasks— list tasksIssues this creates
/v2/taskswill naturally look for/v2/templates,/v2/workflows, etc., which do not exist/templatesthe latest version? Is there a/v2/templatesor/v3/templatesthat supersedes it? No way to know without reading source codeclient.v3.tasks.list()) becomes awkward when most endpoints have no version/templates, should it become/v2/templatesor/v4/templates?Root cause
Based on
backend/src/urls.py, the versioning is historical:/v3/taskswas added as a Zapier-specific endpoint (see# Using by Zapiercomment in urls.py)/v2/taskswas an earlier iteration registered via the DRF routerProposed Solutions
Option A — Unified version prefix (long-term):
Introduce a consistent prefix for all endpoints:
/api/v1/templates,/api/v1/tasks,/api/v1/workflows,/api/v1/users. Maintain old endpoints as aliases during a deprecation period.Option B — Version aliases (non-breaking):
Add aliases so all endpoints are accessible with a consistent prefix (e.g.,
/v3/templates→ alias to/templates). Document/v3/as the recommended prefix.Option C — Documentation only (minimal):
Document the versioning situation clearly: unversioned endpoints = current stable API;
/v2/and/v3/prefixes for tasks are legacy artifacts.Expected Outcome
Developers can predict the URL pattern for any API resource without consulting documentation or source code. All endpoints follow a single, consistent versioning convention.