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 Edge Connector 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. Edge Connector 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, Edge Connector 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 Edge Applications

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

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 Edge Application 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 Edge Application (mandatory), as well as optional components such as Edge Firewall and Custom Pages.

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

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

Example requests

Creating a Workload:

curl --request POST --url https://api.azion.com/v4/workspace/workloads --header 'Accept: application/json' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' --data '{
"name": "Example Workload",
"active": true,
"infrastructure": 1,
"protocols": {
  "http": {
    "versions": [
      "http1",
      "http2"
    ]
  }
},
"workload_domain_allow_access": true
}'

Creating a Workload Deployment:

curl --request POST --url https://api.azion.com/v4/workspace/workloads/<workload_id>/deployments --header 'Accept: application/json' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' --data '{
"name": "Workload Deployment Example",
"current": true,
"active": true,
"strategy": {
  "type": "default",
  "attributes": {
    "edge_application": <edge_application_id>
  }
}
}'

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 Edge Storage without relying on an Edge Application.

Edge Connector

Edge Connector 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 Edge Applications to an origin (your data source), natively incorporating features such as load balancing, HMAC authentication, and Origin Shield.

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

Operational Changes and User-Facing Impact

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

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 Edge 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 Edge Connector.

API Usage

You can manage Edge Connectors 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 an Edge Connector with the Edge Storage Connector Type:

curl --request POST --url https://api.azion.com/v4/edge_connector/connectors --header 'Accept: application/json' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' --data '{
"name": "edge storage connector",
"active": true,
"type": "edge_storage",
"attributes": {
  "bucket": "app-origin",
  "prefix": "/"
}'

Creating an Edge Connector with the HTTP Connector Type:

curl --request POST --url https://api.azion.com/v4/edge_connector/connectors --header 'Accept: application/json' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' --data '{
  "name": "example.com",
  "active": true,
  "type": "http",
  "attributes": {
    "addresses": [
      {
        "active": true,
        "address": "example.com",
        "http_port": 80,
        "https_port": 443,
        "modules": null
      }
    ],
    "connection_options": {
      "dns_resolution": "preserve",
      "transport_policy": "preserve",
      "http_version_policy": "http1_1",
      "host": "example.com",
      "path_prefix": "/",
      "following_redirect": true,
      "real_ip_header": "X-Real-IP",
      "real_port_header": "X-Real-PORT"
    },
    "modules": {
      "load_balancer": {
        "enabled": false,
        "config": null
      },
      "origin_shield": {
        "enabled": false,
        "config": null
      }
    }
  }
}'

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 Edge Application - Origins API endpoints you must update it to use v4 endpoints.

New Features

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

Migration Benefits

• Simplified Backend Management: Edge Connector centralizes all backend connection definitions, reducing configuration complexity. Multiple Edge Applications can use a single Edge Connector, streamlining maintenance and ensuring configuration consistency.
• Future-Ready Architecture: Edge Connector provides the foundation for upcoming Azion Web Platform features and optimizations, ensuring your Edge 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 Edge Connector when fetching the content from your origin.

Custom Pages* replaces Edge Application’s Error Responses settings. All settings previously managed in Edge 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 Edge Application.
  • New behavior: Custom Pages are separate resources and are linked to a Workload.

• Edge Connector per Page Code

  • Previous behavior: All error responses had to have the same Origin.
  • New behavior: You can now assign a specific Edge Connector 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:

curl --request POST --url https://api.azion.com/v4/workspace/custom_pages --header 'Accept: application/json' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' --data '{
"name": "401 error page",
"active": true,
"pages": [
  {
    "code": "401",
    "page": {
      "type": "page_connector",
      "attributes": {
        "connector": <edge_connector_id>,
        "ttl": 300,
        "uri": "/path/error_page.html",
        "custom_status_code": 100
      }
    }
  }
]
}'

Binding a Custom Page to a Workload Deployment:

curl --request POST --url https://api.azion.com/v4/workspace/workloads/<workload_id>/deployments --header 'Accept: application/json' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' --data '{
"name": "Workload Deployment Example",
"current": true,
"active": true,
"strategy": {
  "type": "default",
  "attributes": {
    "edge_application": <edge_application_id>
    "custom_page": <custom_page_id>
  }
}
}'

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 Edge Connector Assignment Assign a specific Edge Connector 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 Edge Connectors.
• 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.