SIA Config API v1 to v3 Migration Guide

ūüöß

Secure Internet Access Configuration API v1 Decommission Notice

Version 1 of the SIA Configuration API was decommissioned on May 5, 2023.
Access to v1 will be terminated on September 8, 2023.
This migration guide is intended to ease the transition to v3 API.

Migration workflow

Review your existing code base used to access the v1 API and note any necessary changes. The two versions largely use the same URIs and parameter namespaces, with a few exceptions, noted below.

Key differences

All of the v1 functionality is available in v3, plus v3 offers a much broader range of capabilities than v1.
NOTE: The Emergency Lists operations are no longer available in v3 - these operations are now supported using the List operations for Policies.
In the case of many GET and POST operations, the v3 response body structure has changed and the response provides more actionable detail.
Refer to the tables below for:

  • v1 operations which have changed in v3
  • new operations added in v3

Security & AUP Categories

v1 Operation/URLv3 Operation/URLChanges in v3
List Security Category Predefined Configurations
/security-categories
List security category predefined configurations
/securityCategories
This feature is now part of the Policy configuration.
List AUP Category Predefined Configurations
/aup-categories
List security category predefined configurations
/securityCategories
This feature is now part of the Policy configuration.

Configurations

Many of the features documented under Configurations in v1 were moved to the Policies, Deployments, Custom Responses, Security Connectors, or Sites configurations in v3. The response body contents of each have changed accordingly.

v1 Operation/URLv3 Operation/URLChanges in v3
List Configurations
/configs
List Configurations
/configs/all
List Configuration Deployments
/configs/{configId}/deployments
List Configuration Deployments
/configs/{configId}/deployments
This feature is now part of Deployments configuration.
Create a Configuration Deployment
configs/{configId}/deployments
Create a Configuration Deployment
configs/{configId}/deployments
This feature is now part of Deployments configuration.
Get a Configuration Deployment
/configs/{configId}/deployments /{configDeploymentId}
Get a Configuration Deployment
/configs/{configId}/deployments /{configDeploymentId}
This feature is now part of Deployments configuration.
List DNS Provisioning Configurations
/configs/{configId}/dnsConfiguration
List DNS-VIPs
/configs/{configId}/dns-vips
This feature is now part of Sites configuration.
List Honeypots
/configs/{configId}/honeypots
List custom responses /configs/{configId}/honeypotsThis feature is now part of Custom Responses.
Create a Honeypot
/configs/{configId}/honeypots
Create a custom response
/configs/{configId}/honeypots
This feature is now part of Custom Responses.
Remove a Honeypot
/configs/{configId}/honeypots /{honeypotId}
Delete a custom response
/configs/{configId}/honeypots /{honeypotId}
This feature is now part of Custom Responses.
Get a Honeypot
/configs/{configId}/honeypots /{honeypotId}
Get a custom response
/configs/{configId}/honeypots /{honeypotId}
This feature is now part of Custom Responses.
Update a Honeypot
/configs/{configId}/honeypots /{honeypotId}
Update a custom response
/configs/{configId}/honeypots /{honeypotId}
This feature is now part of Custom Responses.
Get Recent Changes
/configs/{configId}/recentChanges
List Recent Changes
/configs/{configId}/recentChanges
This feature is now part of the Deployments configuration.

Certificates

In v3, certificates are assigned to proxy configurations within a policy, thus the customerId path parameter has been replaced by configId. Use the path parameter configId to access the existing customerId resources in all certificate operations. You may need to create proxy configurations within existing policies before proceeding.

v1 Operation/URLv3 Operation/URL
List Certificates
/tls/customers/{customerId}/certificates
List Proxy Certificates
/customers/{configId}/certificates
Create a new Certificate
/tls/customers/{customerId} /certificates
Create a new proxy certificate
/customers/{configId}/certificates
Get a Certificate
/tls/customers/{customerId} /certificates/{certificateId}
Get a proxy certificate
customers/{configId}/certificates /{certificateId}
Update a Certificate
/tls/customers/{customerId} /certificates/{certificateId}
Modify a proxy certificate
/customers/{configId}/certificates /{certificateId}
Activate a Certificate
POST /tls/customers/{customerId} /certificates/{certificateId} /op/activate
Activate a proxy certificate
/customers/{configId}/certificates /{certificateId}/op/activate
Confirm Distribution
/tls/customers/{customerId}/certificates {certificateId}/op/confirm-distribution
Confirm proxy certificate distribution
/customers/{configId}/certificates /{certificateId}/op/confirm-distribution
Confirm Download
/tls/customers/{customerId}/certificates /{certificateId}/op/confirm-download
Confirm proxy certificate download
/customers/{configId}/certificates /{certificateId}/op/confirm-download
Deactivate a Certificate
/tls/customers/{customerId}/certificates /{certificateId}/op/deactivate
Deactivate a proxy certificate
/customers/{configId}/certificates /{certificateId}/op/deactivate

Lists

The Lists functionality is documented in its own section in the v3 API reference.

v1 Operation/URLv3 Operation/URL
Get All Lists
/configs/{configId}/lists
List all lists
/configs/{configId}/lists
Get a List
/configs/{configId}/lists/{listId}
Get a list
/configs/{configId}/lists/{listId}
Get All List Deployments
/configs/{configId}/lists/deployments
List all lists
/configs/{configId}/lists
Create a List Deployment
/configs/{configId}/lists/deployments
Create a list
/configs/{configId}/lists
Search in a List
GET /configs/{configId}/lists/items
Search in a List
/configs/{configId}/lists/items
Modify List Items
PUT /configs/{configId}/lists/items
Modify list items
/configs/{configId}/lists/items
Remove a List
DELETE /configs/{configId}/lists/{listId}
Remove a list
/configs/{configId}/lists/{listId}
Patch a List
PATCH /configs/{configId}/lists/{listId}
Patch a list
/configs/{configId}/lists/{listId}
Update a List
PUT /configs/{configId}/lists/{listId}
Update a list
/configs/{configId}/lists/{listId}

Deployments

Request bodies from these operations may contain additional details, including comments and creation/modification/deletion notes.

v1 Operation/URLv3 Operation/URL
Create a Configuration Deployment
/configs/{configId}/deployments
Create a Configuration Deployment
/configs/{configId}/deployments
Get a Configuration Deployment
/configs/{configId}/deployments /{configDeploymentId}
Get a Configuration Deployment
/configs/{configId}/deployments /{configDeploymentId}
List Configuration Deployments
/configs/{configId}/deployments
List Configuration Deployments
/configs/{configId}/deployments
not present in v1List Recent Changes
/configs/{configId}/deployments /{configDeploymentId}/diff

Policies

v1 Operation/URLv3 Operation/URLNew in v3
not present in v1Get policy metadata
/configs/{configId}/policy-metadata
Returns a summary of all configurations applied to a specific policy, including lists, security, AVC, and AUP categories, apps, responses, and custom pages.

Built-in Lists

v1 Operation/URLv3 Operation/URLChanges in v3
Get All Akamai Built-in Security Lists
/akamai-lists
Get All Akamai Built-in Security Lists
/akamai-lists
This feature is now part of the Lists configuration.

Responses

v1 Operation/URLv3 Operation/URLChanges in v3
List Akamai Built-in Responses
/responses
List Akamai Built-in Responses
/responses
This feature is now part of the Policies configuration.

What's new in v3 API

  • Policies - Many of the features documented under Configurations in v1 are now under Policies in v3, such as Security Categories, Responses and Lists.
  • Configurations - New functionality has been added, including contract onboarding, custom error pages and acknowledgements.

The following features provide expanded functionality in v3:

  • Security Connectors - Previously known as Sinkholes. Forwards suspicious or malicious traffic to identify machines that are infected with malware, attempt to download malware, or make requests to command and control servers.
  • Sites and Locations - Allows for more granular policy definition and application.
  • Data Loss Prevention (DLP) Dictionaries - Defines the information types to be monitored for potential data leaks.
  • Client Configurations - Grants control over client installations on a targeted or organizational level.
  • Notifications - Automates communication regarding traffic and access activity.
  • Tenant and Delegated Access - Provides ease of management for customers acting as security providers.
  • Connection Credentials - Controls access to proxy servers

Refer to the v3 API Reference for complete details on these new capabilities.