Cloud API Upgrade Documentation

Overview

IONOS offers multiple application programming interfaces (APIs) for interacting with and managing services in the public cloud ecosystem. One of the most prominent APIs is the IONOS CloudAPI which facilitates virtual data center resources. The latest generation of CloudAPI is version 6, which contains all features and serves as the baseline for future products and updates.

Note: Older versions of IONOS CloudAPI (version 1 through version 5) are announced for End of Life. The endpoints will be sunset on February 1, 2024, and only CloudAPI Version 6 will remain operational.

Users running CloudAPI versions older than version 6 are advised to upgrade to the most recent version.

This documentation shall describe the procedure for upgrading from an older version to CloudAPI version 6. Furthermore, it contains information on which additional features became available in each version as well as breaking changes that require further modifications if respective API resources were used in earlier versions.

IONOS SDKs and Configuration Management Tools

IONOS provides access to various software development kits (SDKs) and configuration management tools. These applications have already been updated to run on CloudAPI version 6.

However, if you are using an IONOS-provided SDK or configuration management tool, you must use the most recent version to ensure that your SDK or configuration management tool interacts with the most recent CloudAPI. More information can be found in the respective GitHub repositories or configuration management tool hubs.

If you don't update older SDKs or configuration management tools, your integration will stop working when CloudAPI versions 1 through 5 are terminated.

API Upgrade Basics

Note: An update of your CloudAPI version will not change your provisioned services or virtual resources. The virtual resources will continue to run without any service interruption.

You can schedule the transition from old CloudAPI versions to new CloudAPI versions according to your business needs, but it must be completed by February 1, 2024. Following that, IONOS will deactivate all CloudAPI endpoints for all legacy versions, leaving only CloudAPI version 6 operational.

During the transition, you can use multiple versions concurrently because most API resources are compatible across CloudAPI versions. There are a few incompatible changes, which are detailed in the version description below. Based on this compatibility, you can apply updates to your implementation in a sequential and step-by-step manner (e.g., API resource by API resource or per individual REST operation).

If you are not satisfied with the results, you can just revert to the previous, older CloudAPI version and make further changes until it meets your requirements.

Your CloudAPI authentication routine remains unchanged, and all authentication options are forward and backward-compatible across all CloudAPI versions.

Backwards-compatible changes

IONOS' CloudAPI is based on previous versions. In most cases, new CloudAPI versions have added major features. Newer versions of CloudAPI are extensions of older versions.

However, in a small number of cases, breaking changes are applied to new CloudAPI versions as well, requiring adaptations to your implementations if your implementation references respective API resources and payloads. These incompatible changes will be highlighted explicitly in the CloudAPI version listed below.

Upgrading your API version

If you’re running an older version of the API, upgrade to the latest version to take advantage of new functionality or streamline responses so the API is faster for you. In most cases, upgrading your API version should be simple:

All CloudAPI HTTP methods contain the version tag in the URL.

Example of old CloudAPI Version (e.g., V2)
Scope of API Call: Create a new virtual data center by using CloudAPI Version 2
HTTP Method: POST https://api.ionos.com/cloudapi/v2/datacenter
Note: Request payload to be added and not provided here for better readability.

To upgrade to the latest version of CloudAPI, you need to change the version tag within the HTTP call. Based on the previous example, the HTTP call would need to look like this:

Example of the latest CloudAPI Version (V6)
Scope of API Call: Create a new virtual data center by using CloudAPI Version 6
HTTP Method: POST https://api.ionos.com/cloudapi/v6/datacenter
Note: Request payload to be added and not provided here for better readability.

In most cases, neither the request nor the response payload changes, but the value options of a request or response property may have been expanded due to the ongoing growth of services. Please confirm by consulting the CloudAPI Version 6 documentation.

Rolling back your API version

Until the expiration date of CloudAPI version 1 - version 5, you can continue to use all versions of CloudAPI, giving you flexibility in your migration strategy. It is not required to migrate the entirety of your implementation to a single CloudAPI version at once. If necessary, you can run an implementation with different versions of the CloudAPI and plan the transition in iterations.

This concept makes it possible to revert to previous CloudAPI versions. Please note that you may be required to undo incompatible changes across CloudAPI versions.

Note: Any change to the CloudAPI version will not result in any changes to the configuration of your virtual infrastructure or services. They will maintain their previous configuration and status.

API versions

This section provides a summary of important changes in each CloudAPI version. If a particular CloudAPI version has introduced incompatible changes then they apply to all previous CloudAPI versions.

It is possible to upgrade from any older CloudAPI version to the latest version, 6. It is not required to iterate the upgrade process through all versions.

The following section will summarize the changes in each version. However, each CloudAPI version documentation is available in the API Documentation portal. You will find a drop-down box at the left top of the documentation website, which allows you to select the CloudAPI version of your choice for further consultation.

CloudAPI V6

CloudAPI Version 6 is the latest version and will remain active. It will receive further functionalities and features but also improvements and bug fixes in the future.

Added features since CloudAPI V5

Added the optional server property type used to provision a Compute Engine or IONOS Cubes (if the property is not provided, the default is ENTERPRISE, which resolves to a Compute Engine).
Added the template server property, which is required when provisioning a CUBE server.
Added the /template resource for retrieving a list of all available CUBE templates. This template does not apply to ENTERPRISE servers.
Added the volume type DAS (direct attached storage based on NVMe), which is automatically applied to every CUBE. This volume type cannot be provisioned independently, meaning you cannot have multiple direct-attached storages per CUBE or mount direct-attached storage volumes on ENTERPRISE server types.
Added volume type expansion for the introduction of SSD Performance classes. SSD is still possible but will resolve to the highest SSD performance class, which the volume type SSD_PREMIUM can explicitly provision. To order an SSD performance class from the lower tier, the volume type must be SSD_STANDARD. No performance class has been introduced for volumes of type HDD or DAS.
Added the volume property userData, which enables cloud-init configuration injection into public Linux images.
Added /flowlogs as a subresource of network interface cards, Managed NAT Gateways, Managed Application Load Balancers, and Managed Network Load Balancers. It specifies which network traffic will be recorded and the S3 bucket where the recordings will be stored.
Added the /natgateways resource to the API, a Managed Network Load Balancer service (TCP/IP Layer 3 load balancer according to the OSI model).
Added the API resource /networkloadbalancers, a Managed Network Load Balancer service (TCP/IP Layer 3 load balancer according to the OSI model).
Added the API resource /applicationloadbalancers, a Managed Application Load Balancer service (an HTTP/HTTPS Layer 7 load balancer in accordance with the OSI model).
Added the API resource /targetgroups, required for configuring the Managed Application Load Balancer.
Added support for bi-directional firewall configuration on network interface cards with CIDR masks.
Added exposure of PCI slot positioning of network interface cards and block storage devices for easier identification within the VM operating system.
Added the API resource /targetgroups required for configuring the Managed Application Load Balancer.

Further, other resources or properties may be visible in the documentation or in the CloudAPI V6 swagger file but are not listed here as they are not active yet.

Deprecated/ Removed features or incompatible changes since CloudAPI V5

CloudAPI V6 is fully compatible with CloudAPI V5 and has introduced new resources, optional properties, and property values. Furthermore, no feature was deprecated from CloudAPI V5.

Note: S3 Key Management has been documented separately in the CloudAPI V6 documentation and the corresponding swagger JSON file, but neither the resource path nor its properties have changed. This revision is made solely for documentation purposes.

CloudAPI V5

Added features since CloudAPI V4

Added the API resource /k8s for managing Kubernetes clusters and node pools.
Added the API resource /backupUnits for managing Backup groups.
Added the volume property backupUnits to define the target of storage volume backup.
Added the API resource /s3keys as a subresource of User Management for managing individual S3 Keys of your user and other users (depending on user role).
Added the functionality to retrieve and manage user information (depending on user role).
Added the meta attributes createdByUserId and lastModifiedByUserId to several resources, such as data centers, servers, volumes, etc., to help track ownership and change history by the user.
Add the API resource /labels to manage labels and associate them with specific resources (data centers, servers, volumes, snapshots, IP blocks).

Deprecated/ Removed features or incompatible changes since CloudAPI V4

Removed the volume property allowReboot of type boolean and indicated whether or not a VM may be rebooted to apply a specific change. When a configuration change to a virtual resource requires a reboot, the VM must be automatically restarted for service reasons. In CloudAPI versions greater than V4, if this property is still set, the CloudAPI will return a parser error.
Incompatibly by changing a required header attribute for resellers from PB-Contract-Number to X-Contract-Number. This header field is required only for resellers who can interact on behalf of their respective customers in customer contracts. This field must be used to uniquely identify a contract from which a reseller wishes to retrieve information or make modifications.

CloudAPI V4

Added features since CloudAPI V3

Added the API resource /um for user management, including management of privileges and permissions.
Added query filter options to CloudAPI resources to apply server-side filtering (e.g., GET all servers of a certain CPU family in the state DEALLOCATED).
Added the /contracts extension to the response payload, which contains information about contract resource limits and current resource utilization.
Added the volume property imageAlias, which allows the assignment of public images via an alias instead of a uuid.
Added the /locations extension to the response payload, which contains information about which image aliases are available in each location.
Added the LAN property ipFailover to prepare failover routines by configuring the same public IP on multiple NICs within a LAN.

Deprecated/ Removed features or incompatible changes since CloudAPI V3

CloudAPI V4 is fully compatible with CloudAPI V3 and has introduced new resources, optional properties, and property values. Furthermore, no feature was deprecated from CloudAPI V3.

CloudAPI V3

Added features since CloudAPI V2

Added the option to download the CloudAPI version swagger file.
Added the volume property availabilityZone to create affinity or anti-affinity of HDD or SSD volumes. This property will not be supported on volumes of type DAS introduced with CloudAPI V6 (see above).
Added REST content types for standard data representation.

Deprecated/ Removed features or incompatible changes since CloudAPI V3

Deprecated custom REST content types for data representation. Providing the custom REST content types in any CloudAPI version higher than V2 will result in an error because these types are no longer known by the API.

CloudAPI V2

Added features since CloudAPI V1

Added the volume property sshKeys (only for public Linux images) and imagePassword (for all public images) to define root access to the operating system following the provisioning of a new operating system. One of both options must be defined when creating a new volume with a public image provided by IONOS.
Added the volume type SSD in addition to the existing type HDD. Please note that in CloudAPI V2, the SSD Performance Classes option has not yet been implemented, and the corresponding property values are not supported/will result in an error.

Deprecated/ Removed features or incompatible changes since CloudAPI V1

CloudAPI V2 is fully compatible with CloudAPI V1 and has introduced new resources, optional properties, and property values. Furthermore, no feature was deprecated from CloudAPI V1.

CloudAPI V1

CloudAPI V1 was the first released RESTful API for interacting with IONOS public cloud services. Therefore, there are no change logs or compatibility issues to be listed. As mentioned before, all CloudAPI versions follow its predecessor.

FAQ

Do I need to modify my user account or contract to use the most recent version of CloudAPI?

No. You can use any version of the CloudAPI anytime without modifying your user account or contracting yourself or through the IONOS support team.

Will my infrastructure change when I upgrade to the latest version of CloudAPI?

No. All services in your infrastructure will continue to work in the exact configuration you set them up. The upgrade will only change the interface towards IONOS which allows you to manage your infrastructure and services.

What will happen if I do not upgrade or complete my upgrade to the latest version of CloudAPI by 30.09.2023?

After September 30, 2023, IONOS will deactivate the CloudAPI endpoints for version 1 up to version 5. Any API call to these versions will not return an error, and the respective API call does not get processed. Your infrastructure will continue to operate in the exact configuration you set them up, but you cannot add, retrieve, modify, or delete any resource anymore. As an alternative, you can use the Data Center Designer (DCD) to continue managing your infrastructure and services until you have completed your upgrade process.

Can I upgrade in small steps or do I need to upgrade all API calls at once?

You can upgrade iteratively and interact with your resources with different CloudAPI versions. For example, you may pool the status of your VM via the latest CloudAPI version already while you still manage the VM with an earlier version. You can define your upgrade schedule according to your technical needs.

Will there be any price changes or changes to service levels?

Upgrading to the latest version of CloudAPI will not change any prices or service level conditions. These are independent of using any interface (DCD, API, SDKs, or Configuration Management Tools).

Will I get charged for additional resources provisioned while doing the upgrade?

Yes. All resources provisioned through any interface in any version will get charged. IONOS cannot determine when you are about to upgrade or work in any particular version productively. From the perspective of IONOS, you are ordering resources that could be used for any workload and, as such, must be billed. Upgrading the CloudAPI requires minimal resources; you can delete any provisioned resource in seconds. You also can execute the upgrade without creating any resources and therefore do not create any cost to your account.

I am using an IONOS SDK or Configuration Management Tool - what shall I do?

Configuration Management Tools are typically built on top of an SDK, and the SDK uses the CloudAPI. All IONOS SDKs and Configuration Management Tools have already been updated to use the most recent version of CloudAPI. As a result, you will need to make sure you are using the most current version of the relevant SDK or Configuration Management Tool. You can find more information in the GitHub repository or Release Documentation Hub. The relevant documentation links are provided on the overview page.

I am using the latest version of CloudAPI already - is there anything I need to consider?

Awesome. There is no further action required.

CloudAPI V6 is "currently" the latest version. Will there be new versions in the future?

Yes! IONOS will introduce changes to the current CloudAPI V6 as long as they do not cause breaking changes or incompatibilities. When this occurs, IONOS will release a new CloudAPI version. CloudAPI V6 will not be phased out immediately. IONOS will provide a timeline and information on whether the older API version will be continued or discontinued. You can be confident that IONOS will ensure that any transition is smooth and with adequate lead time. You may have noticed that IONOS has launched certain services in decoupled endpoints, allowing separate services to establish individual life cycles.

Can IONOS do the upgrade for me?

No. However, we may be able to assist by referring IONOS partners who can provide such services. You should contact your sales representative or key account manager about possible options.

I have questions - what shall I do?

Please contact the IONOS support team which will be available for further assistance.

Troubleshooting

In most cases, the upgrade will be relatively seamless, as the most significant change is made to the URL of your HTTP calls while the request and response payloads remain unchanged. Nevertheless, you may encounter difficulties. Here are some suggestions you may find helpful for initial analysis:

Check the HTTP error code; if it is 404, your basepath, including its version, is incorrect. Make sure it is https://api.ionos.com/cloudapi/v6/. If there are additional HTTP error codes, it may be necessary to verify your credentials.
Check your firewall settings; according to IONOS support experience, applying specific restrictive configurations that define the complete API path, including the version tag, is not recommended. Ensure that the API endpoint and API version provide unrestricted access to the base path. This permits access to all IONOS APIs.
Check the error response message you received; it could be that your HTTP request is valid, but there is an issue with the request payload (in the case of POST calls). Check to see if a property that must be set has been introduced or if a property has been modified. You may wish to consult the CloudAPI Version 6 documentation to determine the correct payload. We hope that all material changes have been listed. Notify the IONOS support team to receive immediate assistance if this is not the case, and the documentation will be updated accordingly.
Check your resource limits; you can test your upgraded scripts before deploying them in production. Keep in mind that this will also consume resources for a brief duration. This counts against your resource limits and may leave your contract without additional resources. You should ensure that you have sufficient capacity by deleting additional resources. If your contract is short on resources, please contact support to increase your resource limits to meet your needs. IONOS does not offer a sandbox mode for its APIs.

Feel free to contact the IONOS support team if you encounter any other trouble during the upgrade.

Last updated 6 months ago