Guides - Upgrade from API v3 to API v4
Programmatic access to the Linode platform, allowing you to automate tasks through a fully-documented REST API.
Version 4 of the Linode API is now in general release and it is a major improvement over previous versions. Almost any task which can be done through the Cloud Manager can now be performed through the API. This guide will show you how to adapt existing code for previous API versions in order to take advantage of these new features.
To get started with the current version, please see the API documentation or our Getting Started with the Linode API guide.
General Changes
The Linode API now uses a standard RESTful architecture. HTTP verbs have predictable results across the API:
Verb Result GET Used to retrieve information about a resource. POST For collections or to create a new resource of that type; also used to perform actions on action endpoints. PUT Update a resource. DELETE Remove a resource from your account. Previous versions of the API allowed users to submit request and method parameters via URL parameters; this is no longer supported. Instead, entity IDs are included in URL paths (e.g.
/linode/instances/1234567
is used to access a Compute Instance with ID 1234567). Additional parameters are passed in the request body.Authentication is now done through the
Authorization
header rather than through the query string.Error codes also follow standard RESTful format (e.g. 2XX for success, 4XX for bad input, 5XX for server errors). The custom error codes from previous versions are no longer used or supported.
Most common static resources can be specified with slugs (e.g.
linode/debian11
for a Debian 11 image) instead of numeric IDs.Batch requests are no longer supported. Many of the actions that previously required multiple requests–such as creating and booting a new Compute Instance or creating and attaching a Block Storage Volume–can now be achieved in a single request.
Modernized language is used throughout the API: “data centers” are now “regions”, “distributions” are now “images”, and “plans” are now “types”.
A new version of the Linode CLI is available to make interacting with the API more convenient.
Creating a Compute Instance
The process for creating a new Compute Instance with the new API has been streamlined. Setting up an instance previously required multiple requests for creating the instance, deploying an image, and booting. All of these steps have been combined, allowing you to get a running Compute Instance with a single request:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-type: application/json" \
-X POST -d '{
"type": "g6-standard-2",
"region": "us-east",
"image": "linode/debian11",
"root_pass": "[password]",
"label": "[label]"
}' \
https://api.linode.com/v4/linode/instances
Examples
This section presents examples of how to convert some of the most common tasks from version 3 of the API to version 4. These example commands output JSON, and a nicer way to view this output is to pipe it into Python’s json.tool
function:
curl https://api.linode.com/v4/regions | python -m json.tool
Compute Instances
List All Instances
View all Compute Instances on your account:
API v3
curl https://api.linode.com/?api_key=sekrit&api_action=linode.list
API v4
In the new API, this is accomplished with a GET request to the
/instances
endpoint:curl -H "Authorization: Bearer $TOKEN" \ https://api.linode.com/v4/linode/instances
Boot a Compute Instance
API v3
curl https://api.linode.com/?api_key=sekrit&api_action=linode.boot&linodeID=123456
API v4
curl -H "Authorization: Bearer $TOKEN" \ -X POST \ https://api.linode.com/v4/linode/instances/$linode_id/boot
NodeBalancers
Data center
has been replaced with region
in the new API and requests must also be converted to RESTful format. For example, creating a new NodeBalancer uses a POST request to the /nodebalancers
endpoint:
API v3
curl https://api.linode.com/?api_key=sekrit&api_action=nodebalancer.create&DatacenterID=123456&Label=this-balancer
API v4
curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -X POST -d '{ "region": "us-east", "label": "nodebalancer_1" }' \ https://api.linode.com/v4/nodebalancers
StackScripts
StackScripts have been moved under the /linode
endpoint. To list all available StackScripts:
API v3
curl https://api.linode.com/?api_key=sekrit&api_action=stackscript.list
API v4
curl https://api.linode.com/v4/linode/stackscripts
This will list all public StackScripts, and if the request is authenticated will also list any private StackScripts on your account. You can use the ID of a StackScript to deploy from that Script when creating a Compute Instance:
curl -H "Authorization: Bearer $TOKEN" \ -H "Content-type: application/json" \ -X POST -d '{ "type": "g6-standard-2", "stackscript_id": 10079, "region": "us-east", "image": "linode/debian11", "root_pass": "[password]", "label": "[label]" }' \ https://api.linode.com/v4/linode/instances
Volumes
Block storage volumes previously were resized through the volume.update
method. This method no longer exists, and resizing is now done through the /resize
endpoint. Note: In both API versions, a block storage volume size can only be increased.
To resize a volume:
API v3
curl https://api.linode.com/?api_key=sekrit&api_action=volume.update&VolumeID=1234&Size=100
API v4
curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -X POST -d '{ "size": 2000 }' \ https://api.linode.com/v4/volumes/$volume_id/resize
DNS
Working with DNS domains and records is similar in both versions. Resources
are now Records
, and are nested beneath the /domains
endpoint.
To create a new A record:
API v3
curl https://api.linode.com/?api_key=sekrit&api_action=domain.resource.create&DomainID=1234&Type=A&Name=sub.example.com&Target=123.456.789.101
API v4
curl -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -X POST -d '{ "type": "A", "target": "123.456.789.101", "name": "sub.example.com" }' \ https://api.linode.com/v4/domains/$domain_id/records
Account
Account interaction has been greatly expanded in the new API. The /accounts
endpoint allows you to view events and notifications on your account, review and make payments, manage account settings and users, and view account information and invoices.
API v3
curl https://api.linode.com/?api_key=sekrit&api_action=account.info
API v4
curl -H "Authorization: Bearer $TOKEN" \ https://api.linode.com/v4/account
Transfer information, previously included in the
account.info
method, can now be accessed through its own endpoint:curl -H "Authorization: Bearer $TOKEN" \ https://api.linode.com/v4/account/transfer
See the API documentation for information about the other new collections under the /account
endpoint.
Utility
Version 3 of the API included utility methods for testing the API and retrieving general information about available plans, data centers, and distributions. The debugging methods api.spec
and test.echo
are not included in version 4, and the avail
information methods have been replaced by GET requests to the corresponding endpoints. Remember that “data centers” are now referred to as “regions”, “distributions” as “images”, and “plans” as “types”.
API v3
curl https://api.linode.com/?api_key=sekrit&api_action=avail.datacenters
curl https://api.linode.com/?api_key=sekrit&api_action=avail.distributions
curl https://api.linode.com/?api_key=sekrit&api_action=avail.linodeplans
API v4
curl https://api.linode.com/v4/regions
curl https://api.linode.com/v4/images
curl https://api.linode.com/v4/linode/types
More Information
You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.
This page was originally published on