API Versioning

API Versioning

The Gateway API has evolved over time, currently supporting two major versions. This guide explains the differences between versions and provides migration guidance.

Version Overview

Version	Prefix	Status	Release	Recommended
2.0	/api/2.0/*	✅ Current	2023	✅ Yes
1.0	/api/1.0/*	⚠️ Legacy	2020	❌ No

[!IMPORTANT] All new integrations should use API v2.0. Version 1.0 is maintained for backwards compatibility only and may be deprecated in future releases.

---

Version 2.0 (Current)

Prefix: /api/2.0/*

Released: 2023

Status: ✅ Active development, recommended for all new integrations

Key Features

• Organized Endpoint Groups: Structured into USER, APP, and WEBCOMPONENT groups
• Improved Authentication: Better scope-based access control
• Standardized Responses: Consistent response format across all endpoints
• Enhanced Middleware: Fine-grained permission control
• Account-based Operations: Support for account-scoped web components
• Client Scopes: Granular scope control for OAuth2 clients

Endpoint Structure

/api/2.0/user/*          # User & OAuth client management
/api/2.0/app/*           # Application-level operations
/api/2.0/webcomponent/*  # Account-scoped operations

Authentication Methods

Endpoint Group	Authentication	Middleware
/api/2.0/user/*	Password Grant	auth:api
/api/2.0/app/*	Client Credentials	client_credentials, auth.app
/api/2.0/webcomponent/*	Account Token	auth.account:webcomponent:*

---

Version 1.0 (Legacy)

Prefix: /api/1.0/*

Released: 2020

Status: ⚠️ Legacy - maintained for backwards compatibility

Characteristics

• Single Endpoint Group: All endpoints in one namespace
• Password Grant Authentication: Only supports auth:api middleware
• Mixed Organization: Less structured endpoint organization
• Limited Scopes: Basic scope control

Endpoint Structure

/api/1.0/users              # User management
/api/1.0/integrations       # Integration management
/api/1.0/services           # Service endpoints
/api/1.0/schedules          # Schedule management

Authentication

All v1.0 endpoints use Password Grant OAuth2:

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "password",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "username": "[email protected]",
  "password": "password",
  "scope": "*"
}

---

Key Differences

1. Endpoint Organization

v1.0:

GET /api/1.0/integrations
POST /api/1.0/integrations
PUT /api/1.0/integrations/{id}
DELETE /api/1.0/integrations/{id}

v2.0:

# App-level (client credentials)
GET /api/2.0/app/integrations
POST /api/2.0/app/integrations
PUT /api/2.0/app/integrations/{id}
DELETE /api/2.0/app/integrations/{id}

# Account-level (web component)
GET /api/2.0/webcomponent/integrations
POST /api/2.0/webcomponent/service/{resource}/install
PUT /api/2.0/webcomponent/integrations/{id}

2. Authentication

v1.0: Only Password Grant

{
  "grant_type": "password",
  "username": "[email protected]",
  "password": "password"
}

v2.0: Multiple grant types with scope control

// Client Credentials for /api/2.0/app/*
{
  "grant_type": "client_credentials",
  "scope": "app:integration-read app:account-read"
}

// Password Grant for /api/2.0/user/*
{
  "grant_type": "password",
  "username": "[email protected]",
  "password": "password"
}

3. Response Format

v1.0: Inconsistent structure

{
  "id": 1,
  "name": "Integration",
  "integrations": [...]
}

v2.0: Standardized with data and meta

{
  "data": {
    "id": 1,
    "name": "Integration"
  },
  "meta": {
    "current_page": 1,
    "total": 10
  }
}

4. Middleware & Permissions

v1.0:

['middleware' => ['auth:api', 'permission:read-integration']]

v2.0:

// APP endpoints
['middleware' => ['client_credentials', 'auth.app', 'client_scopes:app:integration-read']]

// WEBCOMPONENT endpoints
['middleware' => ['auth.account:webcomponent:integration-read']]

5. Scope Granularity

v1.0: Basic scopes

• * - Full access
• Limited custom scopes

v2.0: Fine-grained scopes

• app:account-read, app:account-create, app:account-update
• app:integration-read, app:integration-action, app:integration-claim
• webcomponent:integration-read, webcomponent:integration-event
• And many more…

---

Migration Guide

Migrating from v1.0 to v2.0

[!WARNING] Plan your migration carefully. Test thoroughly in a staging environment before migrating production integrations.

Step 1: Identify Endpoint Equivalents

v1.0 Endpoint	v2.0 Equivalent	Notes
GET /api/1.0/integrations	GET /api/2.0/app/integrations	Use client credentials auth
POST /api/1.0/integrations	POST /api/2.0/app/integrations	Request body structure unchanged
GET /api/1.0/services	GET /api/2.0/app/services	Response format changed
GET /api/1.0/users	GET /api/2.0/user/users	Permission middleware differs

Step 2: Update Authentication

Replace password grant with client credentials where appropriate:

Before (v1.0):

const token = await getPasswordToken(username, password);
const integrations = await fetch('/api/1.0/integrations', {
  headers: { 'Authorization': `Bearer ${token}` }
});

After (v2.0):

const token = await getClientCredentialsToken();
const integrations = await fetch('/api/2.0/app/integrations', {
  headers: { 'Authorization': `Bearer ${token}` }
});

Step 3: Update Response Parsing

Handle the new standardized response format:

Before (v1.0):

const response = await fetch('/api/1.0/integrations');
const integrations = await response.json();
// Direct access to array
integrations.forEach(integration => {...});

After (v2.0):

const response = await fetch('/api/2.0/app/integrations');
const { data, meta } = await response.json();
// Access via data property
data.forEach(integration => {...});
console.log(`Total: ${meta.total}`);

Step 4: Request Specific Scopes

Define minimum required scopes instead of using *:

Before (v1.0):

{
  "scope": "*"
}

After (v2.0):

{
  "scope": "app:integration-read app:integration-action app:account-read"
}

Step 5: Update Error Handling

v2.0 has more consistent error responses:

try {
  const response = await fetch('/api/2.0/app/integrations');
  const { data } = await response.json();
} catch (error) {
  if (error.response?.status === 403) {
    console.error('Missing required scopes');
  } else if (error.response?.status === 422) {
    console.error('Validation errors:', error.response.data.errors);
  }
}

---

Deprecation Timeline

[!CAUTION] Version 1.0 Deprecation Notice

While no specific deprecation date has been announced, v1.0 is considered legacy. We strongly recommend:

1. New Integrations: Use v2.0 exclusively
2. Existing Integrations: Plan migration to v2.0 within 12 months
3. Critical Updates: Security patches will continue for v1.0, but new features are v2.0 only

---

Version Selection Guide

Use v2.0 When:

✅ Building new integrations

✅ Implementing server-to-server automation

✅ Building account-scoped web components

✅ Requiring fine-grained access control

✅ Starting a new project

Use v1.0 When:

⚠️ Maintaining existing integrations (temporarily)

⚠️ Backwards compatibility is critical (short-term only)

❌ Never use v1.0 for new development

---

Testing Both Versions

Use the interactive Swagger documentation to explore both versions:

API Documentation →

The Swagger UI allows you to:

• Compare endpoint structures
• Test authentication flows
• View response schemas
• Experiment with both versions side-by-side

---

FAQs

Can I use both versions simultaneously?

Yes, you can call v1.0 and v2.0 endpoints with different tokens in the same application. However, we recommend migrating fully to v2.0.

Will v1.0 stop working?

Not immediately. v1.0 will be supported for the foreseeable future, but new features are added to v2.0 only.

Do v1.0 and v2.0 share the same database?

Yes, they access the same underlying data. Changes made via v1.0 are visible in v2.0 and vice versa.

Can I migrate gradually?

Yes, you can migrate endpoint by endpoint. Start with read operations, then move to write operations.

Are there breaking changes between versions?

Yes:

• Authentication methods differ
• Response structure is standardized in v2.0
• Endpoint paths have changed
• Middleware requirements differ

---

Next Steps

• View all v2.0 endpoints
• Learn about authentication
• Make your first v2.0 request