API v4 Migration

Migration overview

Azion is rolling out API v4 in the coming months to improve platform performance, flexibility, and resource management. This update is more than an API change, it introduces a new core concept, Workloads and new products like Connectors and Custom Pages, and brings significant enhancements to both the API and Azion Console.

API v4 features a new asynchronous, event-driven architecture designed for higher performance and resilience. The new Workload resource model centralizes configuration, making it easier to manage, reuse, and scale your applications. Connectors enables more flexible and secure backend integrations.

Azion API v4 is now available in Preview for new developer plan accounts and will be released in waves for General Availability (GA) according to your service plan.

Key points about the migration:

• The migration affects both the platform (with the introduction of Workloads, Connectors and Custom Pages) and the API endpoints.
• Some configuration settings have moved to new locations to improve reusability and clarity.
• New accounts will use API v4 by default. Existing accounts will be migrated in waves.
• During the transition, you may see documentation with banners allowing you to switch between v3 and v4 versions of resource.
• After your account is migrated you will not be able to use the the v3 API endpoints or create new Domains, Origins or Error Responses. You must use the equivalent new resources.

API v4 represents a technological shift, providing a foundation for future features and improved operational efficiency across the Azion Web Platform.

API migration

All API endpoints will be migrated to v4 in waves. To view the available endpoints and parameters, see the API v4 reference.

API v3 is now deprecated and will no longer receive updates. It will be discontinued on a future date. After this date, all operations must be performed exclusively using API v4.

Required action

Automations, scripts, and CI/CD pipelines connected to Azion must be updated to use API v4 by the specified deadline.

New Features

• JWT authentication.
• Activity History via GraphQL for full auditability.
• New event-driven architecture.

Migration Benefits

• Improved performance
• Increased flexibility
• Access to future updates
• Query parameters: You can now use query parameters to customize API requests. Supported options include ordering results by a specific field, and filtering results by a search term or by field value. This allows you to retrieve and organize data according to your requirements.

Changes in Applications

The functionality of Applications remains unchanged. However, some configuration options that were previously managed within Applications have been moved to other components as part of the migration.

Billing and Metrics Changes

When migrating to API v4, there are important changes in how usage is metered and billed. These changes may affect your billing depending on your usage patterns.

Workloads

With the introduction of Workloads, the Requests and Data Transfer metrics are now metered at the Workload level instead of the Application level.

Connectors and Load Balancer

The Data Transfer metric for Load Balancer has changed significantly:

• API v3: Data Transfer was calculated based on all traffic flowing through your Application.
• API v4: Data Transfer is calculated only on the traffic between your Connector and your origin servers (edge-to-origin traffic).

This change may result in cost optimization, as only the backend traffic is now metered for Load Balancer purposes.

Firewall

The Firewall request metering model has been updated:

• API v3: Firewall requests were metered only for firewalls with the Network Shield module enabled.
• API v4: Firewall meters all requests that pass through it, including:
  • Requests processed by WAF
  • Requests processed by Network Shield
  • All requests transiting through Firewall

Origin Shield

With the introduction of Connectors in API v4, a new billing metric is now available:

• API v3: Origin Shield was available as a separate Add-On with a Subscription. No Shielded Connectors were metered.
• API v4: Connectors with Origin Shield module enabled are counted as Shielded Connectors and appear in your billing reports.

API Endpoint Comparison

This section provides a detailed analytical comparison between API v3 and API v4 endpoints, including base URLs, request/response structures, and behavioral differences.

Architecture Overview

Resource Mapping

Domains (v3) → Workloads + Deployments (v4)

In API v3, Domains were a single resource that connected an Application to user traffic. In API v4, this concept is split into Workloads (infrastructure and protocol configuration) and Deployments (binding to Applications and other components).

Endpoint Comparison

Request Payload: Create Domain/Workload

API v3 (Domains):

API v4 (Workloads):

Request Payload: Bind to Application (Deployment)

API v3: Binding occurs automatically during Domain creation via the edge_application_id field.

API v4 (Deployments): A separate request is required:

Response Structure

API v3 Response (Synchronous):

API v4 Response (Asynchronous):

Key Behavioral Differences

Origins (v3) → Connectors (v4)

In API v3, Origins were nested resources under Applications. In API v4, Connectors are independent, top-level resources that can be reused across multiple Applications.

Endpoint Comparison

Request Payload: Create Origin/Connector

API v3 (Origins - Single Origin):

API v3 (Origins - Load Balancer):

API v4 (Connectors - HTTP Type):

API v4 (Connectors - Object Storage Type):

Response Structure

API v3 Response:

API v4 Response:

Key Behavioral Differences

Activating a Connector/Origin in an Application

API v3 - Rules Engine:

API v4 - Rules Engine:

Error Responses (v3) → Custom Pages (v4)

In API v3, Error Responses were nested under Applications. In API v4, Custom Pages are independent resources linked to Workloads via Deployments.

Endpoint Comparison

Request Payload

API v3 (Error Responses):

API v4 (Custom Pages):

Response Structure

API v3 Response:

API v4 Response:

Key Behavioral Differences

Rules Engine Comparison

The Rules Engine structure has significant changes in payload format and behavior naming.

Endpoint Comparison

Request Payload Comparison

API v3 Rules Engine:

API v4 Rules Engine:

Key Behavioral Differences

Creation Flow Comparison

This section illustrates the step-by-step creation flow for a complete application setup.

API v3 Creation Flow (4 requests)

1. Create Application:

   POST /edge_applications

   { "name": "My App", "delivery_protocol": "http,https" }

2. Create Domain:

   POST /domains

   { "name": "My Domain", "edge_application_id": <app_id> }

3. Create Origin:

   POST /edge_applications/<app_id>/origins

   { "name": "My Origin", "origin_type": "single_origin", "addresses": [...] }

4. Create Rule to activate Origin:

   POST /edge_applications/<app_id>/rules_engine/request/rules

   { "behaviors": [{ "name": "set_origin", "target": <origin_id> }] }

API v4 Creation Flow (5 requests)

1. Create Application:

   POST /edge_application/applications

   { "name": "My App" }

2. Create Workload:

   POST /workspace/workloads

   { "name": "My Workload", "infrastructure": 1 }

3. Create Workload Deployment:

   POST /workspace/workloads/<workload_id>/deployments

   { "strategy": { "type": "default", "attributes": { "edge_application": <app_id> } } }

4. Create Connector:

   POST /edge_connector/connectors

   { "name": "My Connector", "type": "http", "attributes": {...} }

5. Create Rule to activate Connector:

   POST /edge_application/applications/<app_id>/request_rules

   { "behaviors": [{ "type": "set_edge_connector", "attributes": { "value": <connector_id> } }] }

Billing Implications by Endpoint

Workloads

Azion has adopted the Workload concept to centralize application logic, separating business rules from infrastructure. This enables, reuse, and consistent policy application across environments, following a model inspired by Kubernetes.

Workloads replace Azion Domains. All settings previously managed in Azion Domains are now organized under Workloads.

Operational Changes and User-Facing Impact

The following settings have moved from Azion Domains to Workloads.

Delivery Settings previously configured within an Applications can now be found in Workloads under Protocol Settings:

• Protocol Settings
• Delivery Ports
• Minimum TLS version
• TLS Ciphers

Notable Behavioral Changes

• CNAME Access Only
  • Previous behavior: When enabled, the application could only be accessed via CNAME (for example, app.example.com).
  • New behavior: Replaced by “Workload Domain Allow Access,” enabling access through the auto-generated workload URL (for example, xxxxxxxx.map.azionedge.net).

API Usage

Each Workload is implicitly associated with a Deployment. The Deployment defines the relationship between the Workload and the Applications (mandatory), as well as optional components such as Firewall and Custom Pages.

When creating a Workload via the API, you must also create a Workload Deployment to bind the Workload to an Applications. This association ensures that the Workload is correctly linked to the intended Applications.

When using the Console, this association is created automatically when you select Deployment Settings.

Example requests

Creating a Workload:

Creating a Workload Deployment:

What happens to my existing Domains?

Domains will be automatically converted to Workloads in phases, ensuring compatibility with the original configurations. The migration will occur in waves.

After your account is migrated you’ll not be able to create new Domains.

Required action

If you have an automation that currently uses the Domains API endpoints you must update it to use v4 Workloads endpoints.

New Features

• Custom Pages: Replaces and expands on the previous Error Responses feature. More details are provided below.
• Azion Custom Domain: You to set up a Azion Custom Domain for your application using the format example.azion.app.

Migration Benefits

• Improved Organization: Logically group all resources related to an application or service into a single unit (Workload), making management, visualization, and navigation more efficient. This structure creates clear relationships between components.
• Scalability and Flexibility: Simplifies deployment, updates, and scaling of complex applications by allowing all required components to be managed as part of a Workload.
• Simplified Management: Centralizes configuration and control of different application elements, reducing operational complexity.
• Foundation for New Capabilities: Required for future features such as configuration versioning and more intuitive service connections, for example, linking a domain directly to Object Storage without relying on an Applications.

Connectors

Connectors centralizes backend connection settings, allowing you to reuse them across multiple applications, and provides granular control over performance, security, and routing through a unified interface for connecting Applications to an origin (your data source), natively incorporating features such as load balancing, HMAC authentication, and Origin Shield.

Connectors* replaces Applications’s Origin settings. All settings previously managed in Applications Origins tab are now organized under Connectors.

Operational Changes and User-Facing Impact

All settings previously managed in Applications Origins tab are now organized under Connectors.

Notable Behavioral Changes

• Connector Type

  • Previous behavior: Options included Single Origin and Load Balancer. This defined whether you could configure one or multiple origins.
  • New behavior: Single Origin and Load Balancer types have been unified into the HTTP type. When using multiple origins, you must enable the Load Balancer Module to add more origins.

• HMAC Authentication

  • Previous behavior: Availiable when configuring an Origin.
  • New behavior: Now you must enable the Origin Shield Module when configuring an HTTP type connector.

• Timeouts

  • Previous behavior: Connection Timeout and Between Bytes Timeout had fixed values.
  • New behavior: Now you can configure Connection Timeout and Read/Write Timeout values in the Load Balancer Configuration section of the connector.

API Usage

You can manage Connectorss and their configuration through the API using the available v4 endpoints. Refer to the API reference for details on supported operations and parameters.

Example requests

Creating a connector with the Object Storage Connector Type:

Creating a connector with the HTTP Connector Type:

What happens to my existing Origins?

Existing Origins will be migrated according to a schedule, which will be communicated for each case. The migration will occur in phases.

Required action

If you have an automation that currently uses the Applications - Origins API endpoints you must update it to use v4 endpoints.

New Features

• Configuration reusability: The same Connectors can be can be connected to multiple Applications.
• Configurable timeouts Connection Timeout and Read/Write Timeout values can be configured in the Load Balancer Configuration section of the Connectors.

Migration Benefits

• Simplified Backend Management: Connectors centralizes all backend connection definitions, reducing configuration complexity. Multiple Applications can use a single Connectors, streamlining maintenance and ensuring configuration consistency.
• Future-Ready Architecture: Connectors provides the foundation for upcoming Azion Web Platform features and optimizations, ensuring your Applications are ready to leverage new capabilities as they become available.

Custom Pages

Custom Pages is an Azion feature that allows you to customize error pages for users based on the status code received from an Connectors when fetching the content from your origin.

Custom Pages* replaces Applications’s Error Responses settings. All settings previously managed in Applications’ Error Responses tab are now organized under Custom Pages.

Operational Changes and User-Facing Impact

All settings previously managed in Edge Aplications Error Responses tab are now organized under Custom Pages.

Notable Behavioral Changes

• Relationship

  • Previous behavior: Error pages were a part of an Applications.
  • New behavior: Custom Pages are separate resources and are linked to a Workload.

• Connectors per Page Code

  • Previous behavior: All error responses had to have the same Origin.
  • New behavior: You can now assign a specific Connectors to each error response page code in Custom Pages. This allows you to customize the response for each error code individually.

API Usage

You can manage Custom Pages and their configuration through the API using the available v4 endpoints. Refer to the API reference for details on supported operations and parameters.

To use a Custom Page, you must link it to a Workload using the Workload deployment endpoint. When using the Console, this association is created under a Workload’s deployment setting.

Example requests

Creating a Custom Page:

Binding a Custom Page to a Workload Deployment:

What happens to my existing Error Responses?

Existing Error Responses will be automatically converted to Custom Pages in phases, maintaining compatibility with the original configurations. The migration will occur in waves.

New Features

• Response Details: Customize the response for an status code. Specify the URI, status code, TTL to be returned to the client.
• Per-Status Code Connectors Assignment Assign a specific Connectors to each error response page code in Custom Pages. This allows you to customize the response for each error code individually.

Migration Benefits

• Comprehensive Configuration Options:
  • Define a custom status code for each page.
  • Set the response Time to Live (TTL).
  • Specify the path to the custom page.
  • Link each custom page to one or more Connectorss.
• Activation and Management:
  • Enable or disable any Custom Page using a status toggle.
  • View and manage a paginated list of all configured status codes through the user interface.

Planned migration timeline

The migration process will occur over the next six months.

Recommendations

Here are recommended actions to ensure a smooth migration:

• Monitor Azion communications: Stay informed about migration dates, guides, and any tools provided for the transition.
• Plan your migration: Assess how your current settings will fit into the new structure and strategically plan the migration of your resources.
• Prepare your team: Ensure your team understands the Workloads concept and its impact on application development and deployment on the Azion Web Platform.
• Test new features: As the new features are implemented, test the new capabilities to optimize your applications and services.

Q&A

How can I test the new features?

New Developer accounts will have access to the updated features. To evaluate these features, you can create a personal account that is not associated with your organization’s account. This allows you to test the new functionality independently.

Do I have to do something?

Most users will not need to take any action, as the migration process is automatic and preserves existing configurations. However, if you use custom automation, scripts, or CI/CD pipelines that interact with the previous API endpoints, you must update them to use the new v4 endpoints. Review your integrations to ensure compatibility after migration.

What should I do if I need assistance?

You can contact our support team or ask Azion Copilot.