diff --git a/src/content/docs/en/pages/main-menu/reference/secure/api-v4-migration.mdx b/src/content/docs/en/pages/main-menu/reference/secure/api-v4-migration.mdx index 485b5ad922..6758364e60 100644 --- a/src/content/docs/en/pages/main-menu/reference/secure/api-v4-migration.mdx +++ b/src/content/docs/en/pages/main-menu/reference/secure/api-v4-migration.mdx @@ -72,6 +72,714 @@ The functionality of Applications remains unchanged. However, some configuration --- +## 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. + +| Metric | API v3 (Applications) | API v4 (Workloads) | +|--------|----------------------|-------------------| +| Requests | Metered per Application | Metered per Workload | +| Data Transfer | Metered per Application | Metered per Workload | + +:::tip +After migration, you'll see Requests and Data Transfer metrics in your Workload's dashboard and billing reports. The measured values remain the same as before migration. +::: + +### Connectors and Load Balancer + +The Data Transfer metric for Load Balancer has changed significantly: + +| Metric | API v3 | API v4 | +|--------|--------|--------| +| Load Balancer Data Transfer | All traffic through the Application | Only traffic between Connector and Origin | + +- **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: + +| Metric | API v3 | API v4 | +|--------|--------|--------| +| Firewall Requests | Only firewalls with Network Shield enabled | All firewalls (all requests passing through) | + +- **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 + +:::note +This consolidated approach means you may see an increase in Firewall request counts after migration, as all requests passing through any Firewall are now metered, not just those with Network Shield enabled. +::: + +### Origin Shield + +With the introduction of Connectors in API v4, a new billing metric is now available: + +| Metric | API v3 | API v4 | +|--------|--------|--------| +| Shielded Connectors | Not available | Number of Connectors with Origin Shield enabled | + +- **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. + +:::tip +This is a new metric. If you enable Origin Shield on your Connectors, you'll see Shielded Connectors in your billing reports after migration. +::: + +--- + +## 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 + +| Aspect | API v3 | API v4 | +|--------|--------|--------| +| Base URL | `https://api.azionapi.net/` | `https://api.azion.com/v4/` | +| Architecture | Synchronous | Asynchronous (event-driven) | +| Authentication | Token in header | Token or JWT in header | +| Response Format | Direct results in `results` object | State-based with `state` and `data` objects | +| Resource Model | Nested resources under Applications | Independent resources linked via Deployments | +| API Version Header | `Accept: application/json; version=3` | Not required | + +### Resource Mapping + +| API v3 Resource | API v3 Endpoint | API v4 Resource | API v4 Endpoint | +|-----------------|-----------------|-----------------|-----------------| +| Domains | `/domains` | Workloads | `/workspace/workloads` | +| Origins | `/edge_applications/{id}/origins` | Connectors | `/edge_connector/connectors` | +| Error Responses | `/edge_applications/{id}/error_responses` | Custom Pages | `/workspace/custom_pages` | +| Applications | `/edge_applications` | Applications | `/edge_application/applications` | +| Rules Engine | `/edge_applications/{id}/rules_engine` | Rules Engine | `/edge_application/applications/{id}/rules_engine` | +| Cache Settings | `/edge_applications/{id}/cache_settings` | Cache Settings | `/edge_application/applications/{id}/cache_settings` | +| Device Groups | `/edge_applications/{id}/device_groups` | Device Groups | `/edge_application/applications/{id}/device_groups` | +| Functions | `/edge_functions/functions` | Functions | `/edge_functions/functions` | +| Digital Certificates | `/digital_certificates` | Digital Certificates | `/digital_certificates/certificates` | +| Edge Firewall | `/edge_firewall` | Edge Firewall | `/edge_firewall/firewalls` | +| Network Lists | `/network_lists` | Network Lists | `/workspace/network_lists` | + +--- + +### 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 + +| Operation | API v3 | API v4 | +|-----------|--------|--------| +| List all | `GET /domains` | `GET /workspace/workloads` | +| Get one | `GET /domains/{domain_id}` | `GET /workspace/workloads/{workload_id}` | +| Create | `POST /domains` | `POST /workspace/workloads` | +| Update | `PATCH /domains/{domain_id}` | `PATCH /workspace/workloads/{workload_id}` | +| Delete | `DELETE /domains/{domain_id}` | `DELETE /workspace/workloads/{workload_id}` | +| Bind to Application | Embedded in Domain creation | `POST /workspace/workloads/{workload_id}/deployments` | + +#### Request Payload: Create Domain/Workload + +**API v3 (Domains):** + +```json +{ + "name": "string", + "cname_access_only": false, + "cnames": ["custom.example.com"], + "digital_certificate_id": null, + "edge_application_id": 1234, + "edge_firewall_id": null, + "is_active": true, + "environment": "production" +} +``` + +**API v4 (Workloads):** + +```json +{ + "name": "string", + "active": true, + "infrastructure": 1, + "protocols": { + "http": { + "versions": ["http1", "http2"] + } + }, + "tls": { + "certificate": null, + "ciphers": 7, + "minimum_version": "tls_1_3" + }, + "domains": ["custom.example.com"], + "workload_domain_allow_access": true +} +``` + +#### 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: + +```json +{ + "name": "string", + "active": true, + "current": true, + "strategy": { + "type": "default", + "attributes": { + "edge_application": 1234, + "edge_firewall": null, + "custom_page": null + } + } +} +``` + +#### Response Structure + +**API v3 Response (Synchronous):** + +```json +{ + "results": { + "id": 5678, + "name": "string", + "cnames": ["custom.example.com"], + "cname_access_only": false, + "digital_certificate_id": null, + "edge_application_id": 1234, + "is_active": true, + "domain_name": "xxxxxxxxxx.map.azionedge.net", + "environment": "production" + } +} +``` + +**API v4 Response (Asynchronous):** + +```json +{ + "state": "pending", + "data": { + "id": 5678, + "name": "string", + "active": true, + "infrastructure": 1, + "last_editor": "user@example.com", + "last_modified": "2025-01-15T10:30:00Z", + "domains": ["custom.example.com"], + "workload_domain": "xxxxxxxxxx.map.azionedge.net", + "workload_domain_allow_access": true, + "tls": { "certificate": null, "ciphers": 7, "minimum_version": "tls_1_3" }, + "protocols": { "http": { "versions": ["http1", "http2"] } } + } +} +``` + +#### Key Behavioral Differences + +| Aspect | API v3 | API v4 | +|--------|--------|--------| +| Creation flow | Single request creates Domain and binds to Application | Two-step: Create Workload, then create Deployment | +| Identifier | Numeric `id` | Numeric `id` (Workload) + separate Deployment ID | +| CNAME Access | `cname_access_only` boolean | `workload_domain_allow_access` boolean | +| Environment | `environment: "production"` or `"staging"` | `infrastructure: 1` (Production) or `2` (Staging) | +| Response | Immediate, synchronous | Asynchronous with `state: "pending"` | +| mTLS | Fields on Domain | Separate `mtls` object with verification, certificate, crl | + +--- + +### 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 + +| Operation | API v3 | API v4 | +|-----------|--------|--------| +| List all | `GET /edge_applications/{app_id}/origins` | `GET /edge_connector/connectors` | +| Get one | `GET /edge_applications/{app_id}/origins/{origin_key}` | `GET /edge_connector/connectors/{connector_id}` | +| Create | `POST /edge_applications/{app_id}/origins` | `POST /edge_connector/connectors` | +| Update | `PATCH /edge_applications/{app_id}/origins/{origin_key}` | `PATCH /edge_connector/connectors/{connector_id}` | +| Delete | `DELETE /edge_applications/{app_id}/origins/{origin_key}` | `DELETE /edge_connector/connectors/{connector_id}` | + +#### Request Payload: Create Origin/Connector + +**API v3 (Origins - Single Origin):** + +```json +{ + "name": "My Origin", + "origin_type": "single_origin", + "addresses": [ + { "address": "origin.example.com" } + ], + "origin_protocol_policy": "https", + "host_header": "www.example.com", + "origin_path": "/api", + "connection_timeout": 60, + "timeout_between_bytes": 120, + "hmac_authentication": false, + "hmac_region_name": "", + "hmac_access_key": "", + "hmac_secret_key": "" +} +``` + +**API v3 (Origins - Load Balancer):** + +```json +{ + "name": "My Load Balanced Origin", + "origin_type": "load_balancer", + "addresses": [ + { "address": "origin1.example.com", "weight": 1, "server_role": "primary" }, + { "address": "origin2.example.com", "weight": 1, "server_role": "primary" } + ], + "origin_protocol_policy": "https", + "host_header": "www.example.com" +} +``` + +**API v4 (Connectors - HTTP Type):** + +```json +{ + "name": "My Connector", + "active": true, + "type": "http", + "attributes": { + "addresses": [ + { + "active": true, + "address": "origin.example.com", + "http_port": 80, + "https_port": 443 + } + ], + "connection_options": { + "dns_resolution": "preserve", + "transport_policy": "force_https", + "http_version_policy": "http1_1", + "host": "www.example.com", + "path_prefix": "/api", + "following_redirect": false, + "real_ip_header": "X-Real-IP", + "real_port_header": "X-Real-PORT" + }, + "modules": { + "load_balancer": { + "enabled": false, + "config": { + "method": "round_robin", + "max_retries": 0, + "connection_timeout": 60, + "read_write_timeout": 120 + } + }, + "origin_shield": { + "enabled": false, + "config": null + } + } + } +} +``` + +**API v4 (Connectors - Object Storage Type):** + +```json +{ + "name": "My Storage Connector", + "active": true, + "type": "edge_storage", + "attributes": { + "bucket": "my-bucket", + "prefix": "/" + } +} +``` + +#### Response Structure + +**API v3 Response:** + +```json +{ + "results": { + "origin_id": 123, + "origin_key": "abc123def456", + "name": "My Origin", + "origin_type": "single_origin", + "addresses": [ + { "address": "origin.example.com", "weight": null, "server_role": "primary", "is_active": true } + ], + "origin_protocol_policy": "https", + "host_header": "www.example.com", + "origin_path": "/api", + "connection_timeout": 60, + "timeout_between_bytes": 120 + } +} +``` + +**API v4 Response:** + +```json +{ + "state": "pending", + "data": { + "id": 789, + "name": "My Connector", + "active": true, + "type": "http", + "last_editor": "user@example.com", + "last_modified": "2025-01-15T10:30:00Z", + "attributes": { + "addresses": [ + { "active": true, "address": "origin.example.com", "http_port": 80, "https_port": 443 } + ], + "connection_options": { + "dns_resolution": "preserve", + "transport_policy": "force_https", + "host": "www.example.com", + "path_prefix": "/api" + }, + "modules": { "load_balancer": { "enabled": false }, "origin_shield": { "enabled": false } } + } + } +} +``` + +#### Key Behavioral Differences + +| Aspect | API v3 | API v4 | +|--------|--------|--------| +| Resource scope | Nested under Application | Independent top-level resource | +| Reusability | One Origin per Application | One Connector can serve multiple Applications | +| Type distinction | `origin_type: "single_origin"` or `"load_balancer"` | `type: "http"` with `load_balancer` module enabled for multiple addresses | +| Protocol policy | `origin_protocol_policy` | `connection_options.transport_policy` | +| Host header | `host_header` | `connection_options.host` | +| Path | `origin_path` | `connection_options.path_prefix` | +| Timeouts | `connection_timeout`, `timeout_between_bytes` | `modules.load_balancer.config.connection_timeout`, `read_write_timeout` | +| HMAC Auth | Direct fields on Origin | Requires `origin_shield` module | +| Ports | Not configurable | `http_port`, `https_port` per address | +| Identifier | `origin_key` used for updates | `id` used for all operations | + +#### Activating a Connector/Origin in an Application + +**API v3 - Rules Engine:** + +```json +{ + "name": "Set Origin Rule", + "behaviors": [ + { "name": "set_origin", "target": "" } + ], + "criteria": [ + [{ "variable": "${uri}", "operator": "is_equal", "conditional": "if", "input_value": "/api" }] + ] +} +``` + +**API v4 - Rules Engine:** + +```json +{ + "name": "Set Connector Rule", + "active": true, + "criteria": [ + { "conditional": "if", "variable": "${uri}", "operator": "is_equal", "argument": "/api" } + ], + "behaviors": [ + { "type": "set_edge_connector", "attributes": { "value": "" } } + ] +} +``` + +--- + +### 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 + +| Operation | API v3 | API v4 | +|-----------|--------|--------| +| List all | `GET /edge_applications/{app_id}/error_responses` | `GET /workspace/custom_pages` | +| Get one | `GET /edge_applications/{app_id}/error_responses/{error_id}` | `GET /workspace/custom_pages/{page_id}` | +| Create | `POST /edge_applications/{app_id}/error_responses` | `POST /workspace/custom_pages` | +| Update | `PATCH /edge_applications/{app_id}/error_responses/{error_id}` | `PATCH /workspace/custom_pages/{page_id}` | +| Delete | `DELETE /edge_applications/{app_id}/error_responses/{error_id}` | `DELETE /workspace/custom_pages/{page_id}` | +| Bind to Application | Nested under Application | Via Workload Deployment | + +#### Request Payload + +**API v3 (Error Responses):** + +```json +{ + "name": "My Error Pages", + "errors": [ + { + "code": 404, + "uri": "/errors/404.html", + "ttl": 300, + "custom_status_code": 404, + "origin_id": 123 + }, + { + "code": 500, + "uri": "/errors/500.html", + "ttl": 60, + "custom_status_code": 500, + "origin_id": 123 + } + ] +} +``` + +**API v4 (Custom Pages):** + +```json +{ + "name": "My Error Pages", + "active": true, + "pages": [ + { + "code": "404", + "page": { + "type": "page_connector", + "attributes": { + "connector": 456, + "ttl": 300, + "uri": "/errors/404.html", + "custom_status_code": 404 + } + } + }, + { + "code": "500", + "page": { + "type": "page_connector", + "attributes": { + "connector": 789, + "ttl": 60, + "uri": "/errors/500.html", + "custom_status_code": 500 + } + } + } + ] +} +``` + +#### Response Structure + +**API v3 Response:** + +```json +{ + "results": { + "id": 100, + "name": "My Error Pages", + "errors": [ + { "code": 404, "uri": "/errors/404.html", "ttl": 300, "origin_id": 123 } + ] + } +} +``` + +**API v4 Response:** + +```json +{ + "state": "pending", + "data": { + "id": 200, + "name": "My Error Pages", + "active": true, + "last_editor": "user@example.com", + "last_modified": "2025-01-15T10:30:00Z", + "pages": [ + { + "code": "404", + "page": { + "type": "page_connector", + "attributes": { "connector": 456, "ttl": 300, "uri": "/errors/404.html" } + } + } + ] + } +} +``` + +#### Key Behavioral Differences + +| Aspect | API v3 | API v4 | +|--------|--------|--------| +| Resource scope | Nested under Application | Independent top-level resource | +| Origin per error code | Single `origin_id` for all errors | Different `connector` ID per page code | +| Binding | Automatic (nested) | Via Workload Deployment with `custom_page` attribute | +| Code field | `code` (integer) | `code` (string) | +| Page definition | Flat structure in `errors` array | Nested `page` object with `type` and `attributes` | + +--- + +### Rules Engine Comparison + +The Rules Engine structure has significant changes in payload format and behavior naming. + +#### Endpoint Comparison + +| Operation | API v3 | API v4 | +|-----------|--------|--------| +| List request rules | `GET /edge_applications/{id}/rules_engine/request/rules` | `GET /edge_application/applications/{id}/request_rules` | +| List response rules | `GET /edge_applications/{id}/rules_engine/response/rules` | `GET /edge_application/applications/{id}/response_rules` | +| Get one | `GET .../rules_engine/{phase}/rules/{rule_id}` | `GET .../{phase}_rules/{rule_id}` | +| Create | `POST .../rules_engine/{phase}/rules` | `POST .../{phase}_rules` | +| Update | `PATCH .../rules_engine/{phase}/rules/{rule_id}` | `PATCH .../{phase}_rules/{rule_id}` | +| Delete | `DELETE .../rules_engine/{phase}/rules/{rule_id}` | `DELETE .../{phase}_rules/{rule_id}` | + +#### Request Payload Comparison + +**API v3 Rules Engine:** + +```json +{ + "name": "My Rule", + "phase": "request", + "behaviors": [ + { "name": "set_origin", "target": "123" }, + { "name": "redirect_to_https", "target": true } + ], + "criteria": [ + [ + { "variable": "${uri}", "operator": "is_equal", "conditional": "if", "input_value": "/path" } + ] + ], + "order": 1, + "description": "Rule description" +} +``` + +**API v4 Rules Engine:** + +```json +{ + "name": "My Rule", + "active": true, + "behaviors": [ + { "type": "set_edge_connector", "attributes": { "value": "456" } }, + { "type": "redirect_https", "attributes": { "enabled": true } } + ], + "criteria": [ + { "conditional": "if", "variable": "${uri}", "operator": "is_equal", "argument": "/path" } + ], + "description": "Rule description" +} +``` + +#### Key Behavioral Differences + +| Aspect | API v3 | API v4 | +|--------|--------|--------| +| Endpoint path | `/rules_engine/{phase}/rules` | `/{phase}_rules` | +| Behavior format | `{ "name": "...", "target": "..." }` | `{ "type": "...", "attributes": { ... } }` | +| Criteria format | Nested arrays `[[{...}]]` | Flat array `[{...}]` | +| Criteria argument | `input_value` | `argument` | +| Set Origin behavior | `set_origin` | `set_edge_connector` | +| Order field | Explicit `order` field | Implicit ordering by creation | + +--- + +### 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:** + ```bash + POST /edge_applications + { "name": "My App", "delivery_protocol": "http,https" } + ``` + +2. **Create Domain:** + ```bash + POST /domains + { "name": "My Domain", "edge_application_id": } + ``` + +3. **Create Origin:** + ```bash + POST /edge_applications//origins + { "name": "My Origin", "origin_type": "single_origin", "addresses": [...] } + ``` + +4. **Create Rule to activate Origin:** + ```bash + POST /edge_applications//rules_engine/request/rules + { "behaviors": [{ "name": "set_origin", "target": }] } + ``` + +#### API v4 Creation Flow (5 requests) + +1. **Create Application:** + ```bash + POST /edge_application/applications + { "name": "My App" } + ``` + +2. **Create Workload:** + ```bash + POST /workspace/workloads + { "name": "My Workload", "infrastructure": 1 } + ``` + +3. **Create Workload Deployment:** + ```bash + POST /workspace/workloads//deployments + { "strategy": { "type": "default", "attributes": { "edge_application": } } } + ``` + +4. **Create Connector:** + ```bash + POST /edge_connector/connectors + { "name": "My Connector", "type": "http", "attributes": {...} } + ``` + +5. **Create Rule to activate Connector:** + ```bash + POST /edge_application/applications//request_rules + { "behaviors": [{ "type": "set_edge_connector", "attributes": { "value": } }] } + ``` + +--- + +### Billing Implications by Endpoint + +| Endpoint Change | Billing Impact | +|-----------------|----------------| +| Domains → Workloads | Requests and Data Transfer metered per Workload instead of per Application | +| Origins → Connectors | Load Balancer Data Transfer now only measures edge-to-origin traffic, not all Application traffic | +| Error Responses → Custom Pages | No direct billing impact; depends on Connector usage | +| Rules Engine | No direct billing impact | + +--- + ## 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. diff --git a/src/content/docs/pt-br/pages/menu-principal/referencia/secure/api-v4-migration.mdx b/src/content/docs/pt-br/pages/menu-principal/referencia/secure/api-v4-migration.mdx index f8ac028603..8634420131 100644 --- a/src/content/docs/pt-br/pages/menu-principal/referencia/secure/api-v4-migration.mdx +++ b/src/content/docs/pt-br/pages/menu-principal/referencia/secure/api-v4-migration.mdx @@ -71,6 +71,714 @@ A funcionalidade das Applications permanece inalterada. No entanto, algumas opç | Applications > Load Balancer | Connectors | --- +## Mudanças de cobrança e métricas + +Ao migrar para a API v4, há mudanças importantes na forma como o uso é medido e cobrado. Essas mudanças podem afetar seu faturamento dependendo dos seus padrões de uso. + +### Workloads + +Com a introdução dos Workloads, as métricas de **Requests** e **Data Transfer** passam a ser medidas no nível do Workload em vez do nível da Application. + +| Métrica | API v3 (Applications) | API v4 (Workloads) | +|--------|----------------------|-------------------| +| Requests | Medidas por Application | Medidas por Workload | +| Data Transfer | Medidas por Application | Medidas por Workload | + +:::tip +Após a migração, você verá as métricas de Requests e Data Transfer no dashboard e nos relatórios de faturamento do seu Workload. Os valores medidos permanecem os mesmos de antes da migração. +::: + +### Connectors e Load Balancer + +A métrica de Data Transfer do Load Balancer foi alterada significativamente: + +| Métrica | API v3 | API v4 | +|--------|--------|--------| +| Load Balancer Data Transfer | Todo o tráfego da Application | Apenas tráfego entre Connector e Origin | + +- **API v3**: Data Transfer era calculado com base em todo o tráfego que passava pela sua Application. +- **API v4**: Data Transfer é calculado apenas sobre o tráfego entre seu Connector e seus servidores de origem (tráfego edge-to-origin). + +Essa mudança pode resultar em otimização de custos, pois apenas o tráfego de backend passa a ser medido para fins de Load Balancer. + +### Firewall + +O modelo de mensuração de requests do Firewall foi atualizado: + +| Métrica | API v3 | API v4 | +|---------|--------|--------| +| Firewall Requests | Apenas firewalls com Network Shield habilitado | Todos os firewalls (todas as requests que passam) | + +- **API v3**: Requests do Firewall eram mensuradas apenas para firewalls com o módulo Network Shield habilitado. +- **API v4**: O Firewall mede todas as requests que passam por ele, incluindo: + - Requests processadas pelo WAF + - Requests processadas pelo Network Shield + - Todas as requests que transitam pelo Firewall + +:::note +Essa abordagem consolidada significa que você pode ver um aumento na contagem de requests do Firewall após a migração, pois todas as requests que passam por qualquer Firewall agora são medidas, não apenas aquelas com Network Shield habilitado. +::: + +### Origin Shield + +Com a introdução dos Connectors na API v4, uma nova métrica de cobrança está disponível: + +| Métrica | API v3 | API v4 | +|---------|--------|--------| +| Shielded Connectors | Não disponível | Número de Connectors com Origin Shield habilitado | + +- **API v3**: Origin Shield estava disponível como um Add-On separado com uma Subscription. Nenhum Shielded Connector era medido. +- **API v4**: Connectors com o módulo Origin Shield habilitado são contabilizados como Shielded Connectors e aparecem nos seus relatórios de faturamento. + +:::tip +Esta é uma nova métrica. Se você habilitar Origin Shield nos seus Connectors, verá Shielded Connectors nos seus relatórios de faturamento após a migração. +::: + +--- + +## Comparação de Endpoints da API + +Esta seção fornece uma comparação analítica detalhada entre os endpoints da API v3 e da API v4, incluindo URLs base, estruturas de requisição/resposta e diferenças comportamentais. + +### Visão Geral da Arquitetura + +| Aspecto | API v3 | API v4 | +|---------|--------|--------| +| URL Base | `https://api.azionapi.net/` | `https://api.azion.com/v4/` | +| Arquitetura | Síncrona | Assíncrona (orientada a eventos) | +| Autenticação | Token no header | Token ou JWT no header | +| Formato de Resposta | Resultados diretos no objeto `results` | Baseado em estado com objetos `state` e `data` | +| Modelo de Recursos | Recursos aninhados sob Applications | Recursos independentes vinculados via Deployments | +| Header de Versão da API | `Accept: application/json; version=3` | Não é necessário | + +### Mapeamento de Recursos + +| Recurso API v3 | Endpoint API v3 | Recurso API v4 | Endpoint API v4 | +|----------------|-----------------|----------------|-----------------| +| Domains | `/domains` | Workloads | `/workspace/workloads` | +| Origins | `/edge_applications/{id}/origins` | Connectors | `/edge_connector/connectors` | +| Error Responses | `/edge_applications/{id}/error_responses` | Custom Pages | `/workspace/custom_pages` | +| Applications | `/edge_applications` | Applications | `/edge_application/applications` | +| Rules Engine | `/edge_applications/{id}/rules_engine` | Rules Engine | `/edge_application/applications/{id}/rules_engine` | +| Cache Settings | `/edge_applications/{id}/cache_settings` | Cache Settings | `/edge_application/applications/{id}/cache_settings` | +| Device Groups | `/edge_applications/{id}/device_groups` | Device Groups | `/edge_application/applications/{id}/device_groups` | +| Functions | `/edge_functions/functions` | Functions | `/edge_functions/functions` | +| Digital Certificates | `/digital_certificates` | Digital Certificates | `/digital_certificates/certificates` | +| Edge Firewall | `/edge_firewall` | Edge Firewall | `/edge_firewall/firewalls` | +| Network Lists | `/network_lists` | Network Lists | `/workspace/network_lists` | + +--- + +### Domains (v3) → Workloads + Deployments (v4) + +Na API v3, **Domains** eram um recurso único que conectava uma Application ao tráfego de usuários. Na API v4, esse conceito é dividido em **Workloads** (configuração de infraestrutura e protocolos) e **Deployments** (vinculação com Applications e outros componentes). + +#### Comparação de Endpoints + +| Operação | API v3 | API v4 | +|----------|--------|--------| +| Listar todos | `GET /domains` | `GET /workspace/workloads` | +| Obter um | `GET /domains/{domain_id}` | `GET /workspace/workloads/{workload_id}` | +| Criar | `POST /domains` | `POST /workspace/workloads` | +| Atualizar | `PATCH /domains/{domain_id}` | `PATCH /workspace/workloads/{workload_id}` | +| Deletar | `DELETE /domains/{domain_id}` | `DELETE /workspace/workloads/{workload_id}` | +| Vincular à Application | Incorporado na criação do Domain | `POST /workspace/workloads/{workload_id}/deployments` | + +#### Payload de Requisição: Criar Domain/Workload + +**API v3 (Domains):** + +```json +{ + "name": "string", + "cname_access_only": false, + "cnames": ["custom.example.com"], + "digital_certificate_id": null, + "edge_application_id": 1234, + "edge_firewall_id": null, + "is_active": true, + "environment": "production" +} +``` + +**API v4 (Workloads):** + +```json +{ + "name": "string", + "active": true, + "infrastructure": 1, + "protocols": { + "http": { + "versions": ["http1", "http2"] + } + }, + "tls": { + "certificate": null, + "ciphers": 7, + "minimum_version": "tls_1_3" + }, + "domains": ["custom.example.com"], + "workload_domain_allow_access": true +} +``` + +#### Payload de Requisição: Vincular à Application (Deployment) + +**API v3:** A vinculação ocorre automaticamente durante a criação do Domain através do campo `edge_application_id`. + +**API v4 (Deployments):** Uma requisição separada é necessária: + +```json +{ + "name": "string", + "active": true, + "current": true, + "strategy": { + "type": "default", + "attributes": { + "edge_application": 1234, + "edge_firewall": null, + "custom_page": null + } + } +} +``` + +#### Estrutura de Resposta + +**Resposta API v3 (Síncrona):** + +```json +{ + "results": { + "id": 5678, + "name": "string", + "cnames": ["custom.example.com"], + "cname_access_only": false, + "digital_certificate_id": null, + "edge_application_id": 1234, + "is_active": true, + "domain_name": "xxxxxxxxxx.map.azionedge.net", + "environment": "production" + } +} +``` + +**Resposta API v4 (Assíncrona):** + +```json +{ + "state": "pending", + "data": { + "id": 5678, + "name": "string", + "active": true, + "infrastructure": 1, + "last_editor": "user@example.com", + "last_modified": "2025-01-15T10:30:00Z", + "domains": ["custom.example.com"], + "workload_domain": "xxxxxxxxxx.map.azionedge.net", + "workload_domain_allow_access": true, + "tls": { "certificate": null, "ciphers": 7, "minimum_version": "tls_1_3" }, + "protocols": { "http": { "versions": ["http1", "http2"] } } + } +} +``` + +#### Principais Diferenças Comportamentais + +| Aspecto | API v3 | API v4 | +|---------|--------|--------| +| Fluxo de criação | Única requisição cria Domain e vincula à Application | Dois passos: criar Workload, depois criar Deployment | +| Identificador | `id` numérico | `id` numérico (Workload) + ID de Deployment separado | +| CNAME Access | `cname_access_only` booleano | `workload_domain_allow_access` booleano | +| Ambiente | `environment: "production"` ou `"staging"` | `infrastructure: 1` (Produção) ou `2` (Staging) | +| Resposta | Imediata, síncrona | Assíncrona com `state: "pending"` | +| mTLS | Campos no Domain | Objeto `mtls` separado com verification, certificate, crl | + +--- + +### Origins (v3) → Connectors (v4) + +Na API v3, **Origins** eram recursos aninhados sob Applications. Na API v4, **Connectors** são recursos independentes de nível superior que podem ser reutilizados em múltiplas Applications. + +#### Comparação de Endpoints + +| Operação | API v3 | API v4 | +|----------|--------|--------| +| Listar todos | `GET /edge_applications/{app_id}/origins` | `GET /edge_connector/connectors` | +| Obter um | `GET /edge_applications/{app_id}/origins/{origin_key}` | `GET /edge_connector/connectors/{connector_id}` | +| Criar | `POST /edge_applications/{app_id}/origins` | `POST /edge_connector/connectors` | +| Atualizar | `PATCH /edge_applications/{app_id}/origins/{origin_key}` | `PATCH /edge_connector/connectors/{connector_id}` | +| Deletar | `DELETE /edge_applications/{app_id}/origins/{origin_key}` | `DELETE /edge_connector/connectors/{connector_id}` | + +#### Payload de Requisição: Criar Origin/Connector + +**API v3 (Origins - Single Origin):** + +```json +{ + "name": "My Origin", + "origin_type": "single_origin", + "addresses": [ + { "address": "origin.example.com" } + ], + "origin_protocol_policy": "https", + "host_header": "www.example.com", + "origin_path": "/api", + "connection_timeout": 60, + "timeout_between_bytes": 120, + "hmac_authentication": false, + "hmac_region_name": "", + "hmac_access_key": "", + "hmac_secret_key": "" +} +``` + +**API v3 (Origins - Load Balancer):** + +```json +{ + "name": "My Load Balanced Origin", + "origin_type": "load_balancer", + "addresses": [ + { "address": "origin1.example.com", "weight": 1, "server_role": "primary" }, + { "address": "origin2.example.com", "weight": 1, "server_role": "primary" } + ], + "origin_protocol_policy": "https", + "host_header": "www.example.com" +} +``` + +**API v4 (Connectors - Tipo HTTP):** + +```json +{ + "name": "My Connector", + "active": true, + "type": "http", + "attributes": { + "addresses": [ + { + "active": true, + "address": "origin.example.com", + "http_port": 80, + "https_port": 443 + } + ], + "connection_options": { + "dns_resolution": "preserve", + "transport_policy": "force_https", + "http_version_policy": "http1_1", + "host": "www.example.com", + "path_prefix": "/api", + "following_redirect": false, + "real_ip_header": "X-Real-IP", + "real_port_header": "X-Real-PORT" + }, + "modules": { + "load_balancer": { + "enabled": false, + "config": { + "method": "round_robin", + "max_retries": 0, + "connection_timeout": 60, + "read_write_timeout": 120 + } + }, + "origin_shield": { + "enabled": false, + "config": null + } + } + } +} +``` + +**API v4 (Connectors - Tipo Object Storage):** + +```json +{ + "name": "My Storage Connector", + "active": true, + "type": "edge_storage", + "attributes": { + "bucket": "my-bucket", + "prefix": "/" + } +} +``` + +#### Estrutura de Resposta + +**Resposta API v3:** + +```json +{ + "results": { + "origin_id": 123, + "origin_key": "abc123def456", + "name": "My Origin", + "origin_type": "single_origin", + "addresses": [ + { "address": "origin.example.com", "weight": null, "server_role": "primary", "is_active": true } + ], + "origin_protocol_policy": "https", + "host_header": "www.example.com", + "origin_path": "/api", + "connection_timeout": 60, + "timeout_between_bytes": 120 + } +} +``` + +**Resposta API v4:** + +```json +{ + "state": "pending", + "data": { + "id": 789, + "name": "My Connector", + "active": true, + "type": "http", + "last_editor": "user@example.com", + "last_modified": "2025-01-15T10:30:00Z", + "attributes": { + "addresses": [ + { "active": true, "address": "origin.example.com", "http_port": 80, "https_port": 443 } + ], + "connection_options": { + "dns_resolution": "preserve", + "transport_policy": "force_https", + "host": "www.example.com", + "path_prefix": "/api" + }, + "modules": { "load_balancer": { "enabled": false }, "origin_shield": { "enabled": false } } + } + } +} +``` + +#### Principais Diferenças Comportamentais + +| Aspecto | API v3 | API v4 | +|---------|--------|--------| +| Escopo do recurso | Aninhado sob Application | Recurso independente de nível superior | +| Reutilização | Uma Origin por Application | Um Connector pode servir múltiplas Applications | +| Distinção de tipo | `origin_type: "single_origin"` ou `"load_balancer"` | `type: "http"` com módulo `load_balancer` habilitado para múltiplos endereços | +| Política de protocolo | `origin_protocol_policy` | `connection_options.transport_policy` | +| Host header | `host_header` | `connection_options.host` | +| Path | `origin_path` | `connection_options.path_prefix` | +| Timeouts | `connection_timeout`, `timeout_between_bytes` | `modules.load_balancer.config.connection_timeout`, `read_write_timeout` | +| HMAC Auth | Campos diretos na Origin | Requer módulo `origin_shield` | +| Portas | Não configuráveis | `http_port`, `https_port` por endereço | +| Identificador | `origin_key` usado para updates | `id` usado para todas as operações | + +#### Ativando um Connector/Origin em uma Application + +**API v3 - Rules Engine:** + +```json +{ + "name": "Set Origin Rule", + "behaviors": [ + { "name": "set_origin", "target": "" } + ], + "criteria": [ + [{ "variable": "${uri}", "operator": "is_equal", "conditional": "if", "input_value": "/api" }] + ] +} +``` + +**API v4 - Rules Engine:** + +```json +{ + "name": "Set Connector Rule", + "active": true, + "criteria": [ + { "conditional": "if", "variable": "${uri}", "operator": "is_equal", "argument": "/api" } + ], + "behaviors": [ + { "type": "set_edge_connector", "attributes": { "value": "" } } + ] +} +``` + +--- + +### Error Responses (v3) → Custom Pages (v4) + +Na API v3, **Error Responses** eram aninhados sob Applications. Na API v4, **Custom Pages** são recursos independentes vinculados a Workloads via Deployments. + +#### Comparação de Endpoints + +| Operação | API v3 | API v4 | +|----------|--------|--------| +| Listar todos | `GET /edge_applications/{app_id}/error_responses` | `GET /workspace/custom_pages` | +| Obter um | `GET /edge_applications/{app_id}/error_responses/{error_id}` | `GET /workspace/custom_pages/{page_id}` | +| Criar | `POST /edge_applications/{app_id}/error_responses` | `POST /workspace/custom_pages` | +| Atualizar | `PATCH /edge_applications/{app_id}/error_responses/{error_id}` | `PATCH /workspace/custom_pages/{page_id}` | +| Deletar | `DELETE /edge_applications/{app_id}/error_responses/{error_id}` | `DELETE /workspace/custom_pages/{page_id}` | +| Vincular à Application | Aninhado sob Application | Via Workload Deployment | + +#### Payload de Requisição + +**API v3 (Error Responses):** + +```json +{ + "name": "My Error Pages", + "errors": [ + { + "code": 404, + "uri": "/errors/404.html", + "ttl": 300, + "custom_status_code": 404, + "origin_id": 123 + }, + { + "code": 500, + "uri": "/errors/500.html", + "ttl": 60, + "custom_status_code": 500, + "origin_id": 123 + } + ] +} +``` + +**API v4 (Custom Pages):** + +```json +{ + "name": "My Error Pages", + "active": true, + "pages": [ + { + "code": "404", + "page": { + "type": "page_connector", + "attributes": { + "connector": 456, + "ttl": 300, + "uri": "/errors/404.html", + "custom_status_code": 404 + } + } + }, + { + "code": "500", + "page": { + "type": "page_connector", + "attributes": { + "connector": 789, + "ttl": 60, + "uri": "/errors/500.html", + "custom_status_code": 500 + } + } + } + ] +} +``` + +#### Estrutura de Resposta + +**Resposta API v3:** + +```json +{ + "results": { + "id": 100, + "name": "My Error Pages", + "errors": [ + { "code": 404, "uri": "/errors/404.html", "ttl": 300, "origin_id": 123 } + ] + } +} +``` + +**Resposta API v4:** + +```json +{ + "state": "pending", + "data": { + "id": 200, + "name": "My Error Pages", + "active": true, + "last_editor": "user@example.com", + "last_modified": "2025-01-15T10:30:00Z", + "pages": [ + { + "code": "404", + "page": { + "type": "page_connector", + "attributes": { "connector": 456, "ttl": 300, "uri": "/errors/404.html" } + } + } + ] + } +} +``` + +#### Principais Diferenças Comportamentais + +| Aspecto | API v3 | API v4 | +|---------|--------|--------| +| Escopo do recurso | Aninhado sob Application | Recurso independente de nível superior | +| Origin por código de erro | Único `origin_id` para todos os erros | ID de `connector` diferente por código de página | +| Vinculação | Automática (aninhado) | Via Workload Deployment com atributo `custom_page` | +| Campo code | `code` (inteiro) | `code` (string) | +| Definição de página | Estrutura plana no array `errors` | Objeto `page` aninhado com `type` e `attributes` | + +--- + +### Comparação do Rules Engine + +A estrutura do Rules Engine teve mudanças significativas no formato do payload e na nomenclatura de behaviors. + +#### Comparação de Endpoints + +| Operação | API v3 | API v4 | +|----------|--------|--------| +| Listar regras de request | `GET /edge_applications/{id}/rules_engine/request/rules` | `GET /edge_application/applications/{id}/request_rules` | +| Listar regras de response | `GET /edge_applications/{id}/rules_engine/response/rules` | `GET /edge_application/applications/{id}/response_rules` | +| Obter uma | `GET .../rules_engine/{phase}/rules/{rule_id}` | `GET .../{phase}_rules/{rule_id}` | +| Criar | `POST .../rules_engine/{phase}/rules` | `POST .../{phase}_rules` | +| Atualizar | `PATCH .../rules_engine/{phase}/rules/{rule_id}` | `PATCH .../{phase}_rules/{rule_id}` | +| Deletar | `DELETE .../rules_engine/{phase}/rules/{rule_id}` | `DELETE .../{phase}_rules/{rule_id}` | + +#### Comparação de Payload de Requisição + +**Rules Engine API v3:** + +```json +{ + "name": "My Rule", + "phase": "request", + "behaviors": [ + { "name": "set_origin", "target": "123" }, + { "name": "redirect_to_https", "target": true } + ], + "criteria": [ + [ + { "variable": "${uri}", "operator": "is_equal", "conditional": "if", "input_value": "/path" } + ] + ], + "order": 1, + "description": "Rule description" +} +``` + +**Rules Engine API v4:** + +```json +{ + "name": "My Rule", + "active": true, + "behaviors": [ + { "type": "set_edge_connector", "attributes": { "value": "456" } }, + { "type": "redirect_https", "attributes": { "enabled": true } } + ], + "criteria": [ + { "conditional": "if", "variable": "${uri}", "operator": "is_equal", "argument": "/path" } + ], + "description": "Rule description" +} +``` + +#### Principais Diferenças Comportamentais + +| Aspecto | API v3 | API v4 | +|---------|--------|--------| +| Path do endpoint | `/rules_engine/{phase}/rules` | `/{phase}_rules` | +| Formato de behavior | `{ "name": "...", "target": "..." }` | `{ "type": "...", "attributes": { ... } }` | +| Formato de criteria | Arrays aninhados `[[{...}]]` | Array plano `[{...}]` | +| Argumento do criteria | `input_value` | `argument` | +| Behavior Set Origin | `set_origin` | `set_edge_connector` | +| Campo order | Campo `order` explícito | Ordenação implícita por criação | + +--- + +### Comparação de Fluxo de Criação + +Esta seção ilustra o fluxo passo a passo para configurar uma aplicação completa. + +#### Fluxo de Criação API v3 (4 requisições) + +1. **Criar Application:** + ```bash + POST /edge_applications + { "name": "My App", "delivery_protocol": "http,https" } + ``` + +2. **Criar Domain:** + ```bash + POST /domains + { "name": "My Domain", "edge_application_id": } + ``` + +3. **Criar Origin:** + ```bash + POST /edge_applications//origins + { "name": "My Origin", "origin_type": "single_origin", "addresses": [...] } + ``` + +4. **Criar Regra para ativar Origin:** + ```bash + POST /edge_applications//rules_engine/request/rules + { "behaviors": [{ "name": "set_origin", "target": }] } + ``` + +#### Fluxo de Criação API v4 (5 requisições) + +1. **Criar Application:** + ```bash + POST /edge_application/applications + { "name": "My App" } + ``` + +2. **Criar Workload:** + ```bash + POST /workspace/workloads + { "name": "My Workload", "infrastructure": 1 } + ``` + +3. **Criar Workload Deployment:** + ```bash + POST /workspace/workloads//deployments + { "strategy": { "type": "default", "attributes": { "edge_application": } } } + ``` + +4. **Criar Connector:** + ```bash + POST /edge_connector/connectors + { "name": "My Connector", "type": "http", "attributes": {...} } + ``` + +5. **Criar Regra para ativar Connector:** + ```bash + POST /edge_application/applications//request_rules + { "behaviors": [{ "type": "set_edge_connector", "attributes": { "value": } }] } + ``` + +--- + +### Implicações de Billing por Endpoint + +| Mudança de Endpoint | Impacto no Billing | +|---------------------|-------------------| +| Domains → Workloads | Requests e Data Transfer medidos por Workload em vez de por Application | +| Origins → Connectors | Load Balancer Data Transfer agora mede apenas tráfego edge-to-origin, não todo o tráfego da Application | +| Error Responses → Custom Pages | Sem impacto direto no billing; depende do uso do Connector | +| Rules Engine | Sem impacto direto no billing | + +--- + ## Workloads A Azion adotou o conceito de Workload para centralizar a lógica da aplicação, separando regras de negócio da infraestrutura. Isso permite reutilização e aplicação consistente de políticas entre ambientes, seguindo um modelo inspirado no Kubernetes.