Introduction

With the IBM Cloud® Virtual Private Cloud (VPC) API, you can programmatically provision and manage resources that are part of the IBM VPC Infrastructure as a Service (IaaS) across compute, storage, and networking. For more information on the IBM Cloud® Virtual Private Cloud and VPC resources, see Getting started with Virtual Private Cloud (VPC).

SDKs

SDKs for Java, Node, Python, and Go are available for this API. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes references for using the client libraries.

To learn about using IBM Cloud® Virtual Private Cloud, see:

This documentation describes the Go SDK. For information about the latest Go SDK, see Releases. For instructions and examples on using IBM Cloud services in an IBM Cloud SDK client library, see Using the SDK.

This documentation describes the Java SDK. For information about the latest Java SDK, see Releases. For instructions and examples on using IBM Cloud services in an IBM Cloud SDK client library, see Using the SDK.

This documentation describes the Node SDK. For information about the latest Node SDK, see Releases. For instructions and examples on using IBM Cloud services in an IBM Cloud SDK client library, see Using the SDK.

This documentation describes the Python SDK. For information about the latest Python SDK, see Releases. For instructions and examples on using IBM Cloud services in an IBM Cloud SDK client library, see Using the SDK.

For installation instructions and other information, view the project on GitHub: https://github.com/IBM/vpc-go-sdk/. See also Using the SDK.

For installation instructions and other information, view the project on GitHub: https://github.com/IBM/vpc-java-sdk/. See also Using the SDK.

For installation instructions and other information, view the project on GitHub: https://github.com/IBM/vpc-node-sdk/. See also Using the SDK.

For installation instructions and other information, view the project on GitHub: https://github.com/IBM/vpc-python-sdk/. See also the Python client library for IBM Cloud VPC Services https://pypi.org/project/ibm-vpc/ and Using the SDK.

Endpoint URLs

The IBM Cloud VPC API is available in the following IBM Cloud® regions:

| Location | Region | Public endpoint (service URL) | Private endpoint (service URL) | |--------------------------|------------|------------------------------------------|--------------------------------------------------| | Australia (Sydney) | au-syd | https://au-syd.iaas.cloud.ibm.com/v1 | https://au-syd.private.iaas.cloud.ibm.com/v1 | | Brazil (São Paulo) | br-sao | https://br-sao.iaas.cloud.ibm.com/v1 | https://br-sao.private.iaas.cloud.ibm.com/v1 | | Canada (Montreal) | ca-mon | https://ca-mon.iaas.cloud.ibm.com/v1 | https://ca-mon.private.iaas.cloud.ibm.com/v1 | | Canada (Toronto) | ca-tor | https://ca-tor.iaas.cloud.ibm.com/v1 | https://ca-tor.private.iaas.cloud.ibm.com/v1 | | Germany (Frankfurt) | eu-de | https://eu-de.iaas.cloud.ibm.com/v1 | https://eu-de.private.iaas.cloud.ibm.com/v1 | | Spain (Madrid) | eu-es | https://eu-es.iaas.cloud.ibm.com/v1 | https://eu-es.private.iaas.cloud.ibm.com/v1 | | United Kingdom (London) | eu-gb | https://eu-gb.iaas.cloud.ibm.com/v1 | https://eu-gb.private.iaas.cloud.ibm.com/v1 | | India (Chennai) | in-che | https://in-che.iaas.cloud.ibm.com/v1 | https://in-che.private.iaas.cloud.ibm.com/v1 | | India (Mumbai) | in-mum | https://in-mum.iaas.cloud.ibm.com/v1 | https://in-mum.private.iaas.cloud.ibm.com/v1 | | Japan (Osaka) | jp-osa | https://jp-osa.iaas.cloud.ibm.com/v1 | https://jp-osa.private.iaas.cloud.ibm.com/v1 | | Japan (Tokyo) | jp-tok | https://jp-tok.iaas.cloud.ibm.com/v1 | https://jp-tok.private.iaas.cloud.ibm.com/v1 | | US East (Washington DC) | us-east | https://us-east.iaas.cloud.ibm.com/v1 | https://us-east.private.iaas.cloud.ibm.com/v1 | | US South (Dallas) | us-south | https://us-south.iaas.cloud.ibm.com/v1 | https://us-south.private.iaas.cloud.ibm.com/v1 |

See also Locations for resource deployment.

To call the API, select the service URL that corresponds to the region of your choice and add a method path to form the complete request URL. For example, to list all images available in the us-south region, make a GET request to https://us-south.iaas.cloud.ibm.com/v1/images.

To change the SDK service URL, reinstantiate the service instance with a different region-specific URL. For more information, see Using the SDK.

Example request to call the us-south service URL:

curl -H "Authorization: Bearer {token}" -X {http_method} "https://us-south.iaas.cloud.ibm.com/v1{path}"

Replace {token}, {http_method}, and {path} in this example with the values for your particular request.

Default service URL:

https://us-south.iaas.cloud.ibm.com/v1

Example to change the service URL to the United Kingdom region:

authenticator := &core.IamAuthenticator{
  ApiKey: "{api_key}",
}

// Get the service URL for the specified region
serviceURL, _ := vpcv1.GetServiceURLForRegion("eu-gb")

options := &vpcv1.VpcV1Options{
  Authenticator: authenticator,
  URL: serviceURL,
}

For more information, see Using the SDK.

Default service URL:

https://us-south.iaas.cloud.ibm.com/v1

Example to change the service URL to the United Kingdom region:

Authenticator authenticator = new IamAuthenticator("{api_key}");
Vpc service = new Vpc(Vpc.DEFAULT_SERVICE_NAME, authenticator);
service.setServiceUrl(Vpc.getServiceUrlForRegion("eu-gb"));

For more information, see Using the SDK.

Default service URL:

https://us-south.iaas.cloud.ibm.com/v1

Example to change the service URL to the United Kingdom region:

const options = {
  authenticator: new IamAuthenticator({
    apikey: '{api_key}'
  }),
  serviceUrl: VpcV1.getServiceUrlForRegion("eu-gb"),
};

const service = new VpcV1(options);

For more information, see Using the SDK.

Default service URL:

https://us-south.iaas.cloud.ibm.com/v1

Example to change the service URL to the United Kingdom region:

from ibm_vpc import VpcV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('apikey')
service = VpcV1(authenticator=authenticator)
service.set_service_url(VpcV1.get_service_url_for_region("eu-gb"))

For more information, see Using the SDK.

Authentication

The IBM Cloud VPC API uses Identity and Access Management (IAM) to authenticate requests. To call each API method, you must be assigned a role that includes the required IAM actions. Each method has an Authorization section that lists the required actions and, if applicable, the conditions under which each action is required. Check your access on the IBM Cloud console by navigating to Users > User > Access.

For more information about IAM actions and how they map to roles, see Assigning access to account management services and Managing IAM access for VPC Infrastructure Services.

Learn about obtaining an IAM token for an authenticated user or service ID in the IAM Identity Services API. If you first create an API key, you can use it to generate an IAM token.

To use the API, add a valid IAM token to the HTTP Authorization request header. For example, -H 'Authorization: Bearer {token}'.

To retrieve your access token:

curl -X POST \
  "https://iam.cloud.ibm.com/identity/token" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \
  --data-urlencode 'apikey={api_key}'

To use the API, replace {token} in the following example request with the token obtained from IAM in the previous request. Also replace {http_method} with an HTTP method such as POST, and replace {url} with a request URL such as https://us-south.iaas.cloud.ibm.com/v1/keys:

curl -H "Authorization: Bearer {token}" -X {http_method} "{url}"

When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:

Programmatically, by constructing an IAM authenticator instance and supplying your IAM API key.
Externally, in configuration options that are then used by the SDK to construct an IAM authenticator at run time.

Provide external configuration options by either:

Storing the configuration options in environment variables. When you initialize the service client, the SDK constructs the authenticator by reading the configuration properties directly from the environment variables.
Saving the configuration options in a file. When you initialize the service client, the SDK constructs the authenticator by reading the configuration properties from the file specified by the IBM_CREDENTIALS_FILE environment variable.

In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.

For more information, see the Authentication section in the IBM Cloud SDK Common documentation.

Outside of development and testing, never hard-code secrets (such as IAM API keys) into a client application.

Setting client options programmatically

Construct the service client programmatically, where {api_key} is your hardcoded IAM API key:

import {
  "github.com/IBM/go-sdk-core/v5/core"
  "github.com/IBM/vpc-go-sdk/vpcv1"
}
// Create an IAM authenticator.
authenticator := &core.IamAuthenticator{
  ApiKey: "{api_key}",
}
// Construct an "options" struct for creating the service client.
options := &vpcv1.VpcV1Options{
  Authenticator: authenticator,                            // required
  URL:           "https://us-east.iaas.cloud.ibm.com/v1",  // optional
}
// Construct the service client.
vpcService, err := vpcv1.NewVpcV1(options)
if err != nil {
  panic(err)
}

Service operations can now be invoked using the vpcService variable.

Setting client options through environment variables

Export environment variables to implement service client options, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

export VPC_URL={service_url}
export VPC_AUTH_TYPE=iam
export VPC_APIKEY={api_key}

Construct the service client using external configuration. vpcv1.NewVpcV1UsingExternalConfig() initializes the client with the environment variables, using them for subsequent authentication.

vpcService, err := vpcv1.NewVpcV1UsingExternalConfig()

Setting client options through a credentials file

Store credentials in a file such as my-credentials.env, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

VPC_URL={service_url}
VPC_AUTH_TYPE=iam
VPC_APIKEY={api_key}

Export the name of the file with an environment variable, where {credential_file_path} is the absolute path to your credentials file, such as "$HOME/secrets/vpc-credentials.env".

export IBM_CREDENTIALS_FILE={credential_file_path}

Construct the service client using external configuration. vpcv1.NewVpcV1UsingExternalConfig() initializes with the defined credential file, using it for subsequent authentication.

vpcService, err := vpcv1.NewVpcV1UsingExternalConfig()

Setting client options programmatically

Construct the service client programmatically, where {api_key} is your hardcoded IAM API key.

import com.ibm.cloud.is.vpc.v1.Vpc;
import com.ibm.cloud.sdk.core.security.Authenticator;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;
// Create an IAM authenticator.
Authenticator authenticator = new IamAuthenticator.Builder()
  .apikey("{api_key}")
  .build();
// Construct the service client.
Vpc service = new Vpc(Vpc.DEFAULT_SERVICE_NAME, authenticator);
// Set our custom service URL (optional).
service.setServiceUrl("https://us-east.iaas.cloud.ibm.com/v1");

Setting client options through environment variables

Export environment variables to implement service client options, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

export VPC_URL={service_url}
export VPC_AUTH_TYPE=iam
export VPC_APIKEY={api_key}

Construct the service client using external configuration. Vpc.newInstance() initializes the client with the environment variables, using them for subsequent authentication.

import com.ibm.cloud.is.vpc.v1.Vpc;
Vpc service = Vpc.newInstance();

Setting client options through a credentials file

Store credentials in a file such as my-credentials.env, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

VPC_URL={service_url}
VPC_AUTH_TYPE=iam
VPC_APIKEY={api_key}

Export the name of the file with an environment variable, where {credential_file_path} is the absolute path to your credentials file, such as "$HOME/secrets/vpc-credentials.env".

export IBM_CREDENTIALS_FILE={credential_file_path}

Construct the service client using external configuration. Vpc.newInstance() initializes with the defined credential file, using it for subsequent authentication.

import com.ibm.cloud.is.vpc.v1.Vpc;
Vpc service = Vpc.newInstance();

Setting client options programmatically

Construct the service client programmatically, where {api_key} is your hardcoded IAM API key.

const VpcV1 = require('vpc-node-sdk/vpc/v1');
const { IamAuthenticator } = require('vpc-node-sdk/auth');

// Create an IAM authenticator.
const authenticator = new IamAuthenticator({
  apikey: '{api_key}',
});

// Construct the service client.
const vpcService = new VpcV1({
  authenticator,                                       // required
  serviceUrl: 'https://us-east.iaas.cloud.ibm.com/v1', // optional
});

Setting client options through environment variables

Export environment variables to implement service client options, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

export VPC_URL={service_url}
export VPC_AUTH_TYPE=iam
export VPC_APIKEY={api_key}

Construct the service client using external configuration. VpcV1.newInstance() initializes the client with the environment variables, using them for subsequent authentication.

const VpcV1 = require('vpc-node-sdk/vpc/v1');
const vpcService = VpcV1.newInstance();

Setting client options through a credentials file

Store credentials in a file such as my-credentials.env, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

VPC_URL={service_url}
VPC_AUTH_TYPE=iam
VPC_APIKEY={api_key}

Export the name of the file with an environment variable, where {credential_file_path} is the absolute path to your credentials file, such as "$HOME/secrets/vpc-credentials.env".

export IBM_CREDENTIALS_FILE={credential_file_path}

Construct the service client using external configuration. VpcV1.newInstance() initializes with the defined credential file, using it for subsequent authentication.

const VpcV1 = require('vpc-node-sdk/vpc/v1');
const vpcService = VpcV1.newInstance();

Setting client options programmatically

Construct the service client, where {api_key} is your hardcoded IAM API key

from ibm_vpc import VpcV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

## Create an IAM authenticator.
authenticator = IAMAuthenticator('{api_key}')
## Construct the service client.
service = VpcV1(authenticator=authenticator)
## Set custom service URL (optional)
service.set_service_url('https://us-east.iaas.cloud.ibm.com/v1')

Setting client options through environment variables

Export environment variables to implement service client options, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

export VPC_URL={service_url}
export VPC_AUTH_TYPE=iam
export VPC_APIKEY={api_key}

Construct the service client using external configuration. VpcV1.new_instance() initializes the client with the environment variables, using them for subsequent authentication.

from ibm_vpc import VpcV1
service = VpcV1.new_instance()

Setting client options through a credentials file

Store credentials in a file such as my-credentials.env, where {service_url} is an endpoint URL for the service and {api_key} is an IAM API key.

VPC_URL={service_url}
VPC_AUTH_TYPE=iam
VPC_APIKEY={api_key}

Export the name of the file with an environment variable, where {credential_file_path} is the absolute path to your credentials file, such as "$HOME/secrets/vpc-credentials.env".

export IBM_CREDENTIALS_FILE={credential_file_path}

Construct the service client using external configuration. VpcV1.new_instance() initializes with the defined credential file, using it for subsequent authentication.

from ibm_vpc import VpcV1
service = VpcV1.new_instance()

Authorization

Access to VPC infrastructure resources is managed through IAM. IAM provides the ability to manage resources through resource groups and access management tags. For more information, see Managing IAM access for VPC Infrastructure Services.

Auditing

IBM Cloud services, such as IBM Cloud VPC, generate activity tracking events. Activity tracking events report on activities that change the state of resources in IBM Cloud and also report on certain activities that do not change any state, such as attempts to access and update resources. You can use the events to investigate abnormal activity and critical actions and to comply with regulatory audit requirements.

Monitor API activity within your account by using IBM Cloud Activity Tracker Event Routing, a platform service, to route auditing events to destinations of your choice. Configure targets and routes that define where activity tracking events are sent. Each time you make an API call, one or more events are generated that you can track and audit. Specific event types are listed for each method that generates auditing events. For methods that don't list any events, no events are generated. For more information, see About IBM Cloud Activity Tracker Event Routing and Activity tracking events for IBM Cloud VPC.

You can also use IBM Cloud Logs to visualize and alert on events that are generated in your account and routed by IBM Cloud Activity Tracker Event Routing to an IBM Cloud Logs instance. For more information, see Getting started with IBM Cloud Logs.

Error handling

This API uses standard HTTP response codes to indicate the outcome of a request. A 4xx-series response indicates a failure that the client must resolve. A 5xx-series response indicates a service failure.

| HTTP Error Code | Description | Recovery | |------------------|-------------|-------------| | 400 | Bad Request | The input parameters in the request body are either incomplete, malformed, or too large. Be sure to include all required parameters in your request.| | 401 | Unauthorized | You are not authorized to make this request. Log in to IBM Cloud and try submitting the request again. If this error persists, contact the account owner to check your permissions.| | 403 | Forbidden | The supplied authentication is not authorized to perform the requested operation. Either you do not have valid access through IAM access policies or your request is denied due to the context-based restriction policy. If this error persists, contact the account owner to check your permissions.| | 404 | Not Found | The requested resource could not be found but may be available in the future. | | 405 | Method Not Allowed | The requested resource does not support the request method. | | 406 | Not Acceptable | The resource the client requested is not available in a format allowed by the Accept header supplied by the client. | | 408 | Request Timeout | The connection to the server timed out. Wait a few minutes, and try submitting the request again. | | 409 | Conflict | The request cannot be completed because of a conflict between the request and the current state of the resource. | | 412 | Precondition Failed | The client specified one or more preconditions in its headers, and the server cannot meet those preconditions. | | 426 | Upgrade Required | The server refuses to perform the request using the current protocol but might perform the request after the client upgrades to a different protocol. | | 500 | Internal Server Error | The request cannot be processed because the client encountered an unexpected condition on the server. Wait a few minutes and try submitting the request again. If this error persists, contact IBM Support. | | 501 | Not Implemented | The server either does not recognize the request method, or it lacks the ability to fulfill the request.| | 502 | Bad Gateway | The server was acting as a gateway or proxy and received an invalid response from the upstream server.| | 503 | Service Unavailable | The server cannot process the request. Generally, this condition is temporary, such as when a server is overloaded or down for scheduled maintenance. This condition could also be due to an unplanned outage of a service that is needed to process the request. Wait a few minutes and try submitting the request again. If this error persists, contact IBM Support.| | 504 | Gateway Timeout | The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.| | 505 | HTTP Version Not Supported | The server does not support the HTTP protocol version that is used in the request. |

If the server is unable to perform any part of the requested operation, the entire operation will fail, resulting in no observable change to any of the resources. For example, if a PATCH request is made to change two properties, but the caller is not authorized to change one of the properties, the request will fail with 403 Unauthorized, and the resource will be unchanged. Similarly, if a GET /volumes request is made to retrieve all the caller's volumes in the region, but one of the volumes is using a beta feature that cannot be expressed through the GA API schema, the entire request will fail, resulting in no volumes being returned.

Because the 500 Internal Server Error and 408 Request Timeout HTTP status codes may be generated by entities between your client and the server (such as a reverse proxy), it is possible that the server successfully processed your client's request, but that your client still received 500 or 408 from one of these entities. Therefore, when processing those status codes in response to a DELETE, PATCH, POST, or PUT` request, you must not assume the request failed.

Error handling example:

import "github.com/IBM/vpc-go-sdk/vpcv1"

// Instantiate a service
vpcService, vpcServiceErr := vpcv1.NewVpcV1(options)

// Check for errors
if vpcServiceErr != nil {
  panic(vpcServiceErr)
}

// Call a method
listVpcsOptions := &vpcv1.ListVpcsOptions{}
  vpcs, _, err := vpcService.ListVpcs(listVpcsOptions)

// Check for errors
if err != nil {
  panic(err)
}

Error handling example:

try {
  // Invoke an operation
  Response<Resource> response = service.getResource(options).execute();

  // Process response...

} catch (BadRequestException e) {
  // Handle Bad Request (400) exception
} catch (UnauthorizedException e) {
  // Handle Unauthorized (401) exception
} catch (NotFoundException e) {
  // Handle Not Found (404) exception
} catch (RequestTooLargeException e) {
  // Handle Request Too Large (413) exception
} catch (ServiceResponseException e) {
  // Base class for all exceptions caused by error responses from the service
  System.out.println("Service returned status code "
    + e.getStatusCode() + ": " + e.getMessage());
  System.out.println("Detailed error info:\n" + e.getDebuggingInfo().toString());
}

Error handling example:

try {
    const response = await vpcService.getResource();
    // ...handle successful response...
} catch (err) {
    // ...handle error response...
    console.log("Error status code: " + err.status + " (" + err.statusText + ")");
    console.log("Error message:     " + err.message);
}

Example of error handling:

from ibm_cloud_sdk_core import ApiException

try:
    vpcs = service.list_vpcs().get_result()['vpcs']
except ApiException as e:
    print("List VPC failed with status code " + str(e.code) + ": " + e.message)

Versioning

This reference documents API behavior for any date value in the version parameter between 2025-12-09 and 2026-01-27. To view the reference for an older version of the API, select it from the Version list.

Requests to the VPC API require a major version as the first segment of the request path (/v1/) and a date-based version as a query parameter in the format version=YYYY-MM-DD.

The VPC API supports a continuous series of version dates from 2019-01-01 to today's date (in UTC).

The VPC API adheres to the IBM Cloud API Handbook change compatibility guidelines. As a result, most changes to the VPC API are designed to be compatible with existing clients and are made available to clients that specify any supported version date. For example, support for new paths, new optional parameters, and additional properties in responses are considered backward compatible and, when possible, are made available without respect to the version date specified by a client.

By design, backward-incompatible changes, such as the removal or restructuring of existing properties or parameters, are made available only for clients that specify version dates on or after the feature became available.

To maximize the compatibility of your client with future API changes, follow the best practices for client development.

When you develop a new client, specify the current date (as of the time of development) as a fixed value for the version parameter, and keep that same fixed version date value when you test and ship your client. Do not specify a value for the version parameter that is dynamically computed based on the date your code is compiled or executed.

Features that require clients to specify a later version date are specifically noted in the change log, along with guidance on how to migrate your client to work with newer versions.

As a best practice, review the change log on a periodic basis. To use the latest features and maintain ongoing compatibility, update and test your client with a newer version date. As with new clients, specify the current date (as of the time you update your client code) as a fixed value for the version parameter.

Deprecation

A method, path, parameter, property or other feature will be marked as deprecated when usage is no longer recommended, such as when it's been rendered obsolete by new features. After a feature is deprecated, support for that feature may be removed for clients that specify new version dates.

Features that are no longer supported in new API versions are specifically noted in the change log, along with guidance on how to migrate your client to work with newer versions.

The oldest supported version date (currently 2019-01-01) may be moved forward in the future, necessitating clients to specify a newer version date and make any updates needed to work with that newer version.

Each SDK version uses a corresponding version of the API that it was developed and tested to be compatible with.

Example request to list regions in the API:

curl -X GET \
  "$vpc_api_endpoint/v1/regions?generation=2&version=$version" \
  -H "Authorization: Bearer $iam_token"

Property value expansion

Unless explicitly stated otherwise, relaxing constraints for a property's values is considered a backward-compatible change that is expected to occur to accommodate new features or products. Backward-compatible property value expansion supports the following:

For numeric properties: increasing maximum values or decreasing minimum values
For array properties: increasing maximum item counts or decreasing minimum item counts
For string properties: increasing maximum lengths or decreasing minimum lengths
For cron specification properties: increasing the scheduling frequency
For enumerations: expanding the set of enumerated values
For One of: adding choices to an existing One of selection

For example, the maximum value for the Share iops property in the specification reflects the current maximum IOPS that can be supported by the IBM Cloud VPC File Storage service. However, the value in the specification may be subsequently increased, even for existing API versions. Likewise, the values for enumerations, such as the Share access_control_mode, encryption, and replication_status properties may be subsequently expanded, even for existing API versions. Additionally, a set of One of choices, such as adding another choice for security group targets, may be expanded in the future for existing API versions.

To maximize the compatibility of your client with future API changes, follow the best practices for client development.

Concurrent update protection

To prevent multiple clients from unknowingly overwriting each other's updates, select API methods support entity-tags and conditional requests as specified in RFC 7232.

To make a conditional request, first issue a GET request on the resource to retrieve its up-to-date representation. The response will include an ETag header, whose value is a fingerprint of the resource's current client-configurable state. Next, verify that the method you want to perform (typically an update or a delete) is appropriate given the current state of the resource. For example, you may want to only delete a VPN server if its port property has a specific value. Finally, if the resource is still in the appropriate state, issue the API request, as usual, but make the request conditional by including an If-Match header with its value set to the ETag value from the earlier GET request.

Because the If-Match header was provided, the server will check that the resource's current ETag value (which reflects the client-configurable state) matches the value you provided in the If-Match header. If the two values match, the server can be certain the resource has not been updated in the interim, and request processing continues as usual. Otherwise, the resource was updated (by another client) between the time you issued the GET and the time you issued the conditional request, and the request will fail with 412 Precondition Failed. Because a resource may be updated by another client at any time, clients issuing conditional requests must be written to check for a 412 failure, and if encountered, restart the sequence by reissuing the original GET request.

Because 412 indicates that the resource has been updated, before reissuing the conditional request, the client must both retrieve the latest ETag value using GET and verify that the representation of the resource is still appropriate for the conditional request.

For additional safety, the VPC API requires that any PATCH request that includes an array property must also provide an If-Match header. For example, a PATCH /volumes/{id} request that includes the user_tags array property will fail with 400 Bad Request if the If-Match header is not provided. In contrast, a PATCH /volumes/{id} request to modify just the name string property need not provide an If-Match header (since no array is present). However, if the If-Match header is provided, the server will check its value and will return 412 Precondition Failed if the value is not current.

The ETag and If-Match headers must be used only on methods that have explicit documentation that those headers are supported. Other related headers described in RFC 7232, such as If-None-Match and If-Modified-Since, are not supported at this time.

Maturity query parameter

API requests accept a maturity query parameter. This parameter lets you decide on the level of stability to use before features become generally available.

For the API behavior documented in this reference, omit the maturity query parameter. For information on making beta requests, see the Beta VPC API reference.

Pagination

Some API requests can return many results. To improve performance, results are returned one page at a time, with a limited number of results on each page. The default page size is typically 50 items, with a maximum size of 100.

The default and maximum limits might vary by operation. To specify a different page size, use the limit query parameter.

For a request that uses pagination, the response includes additional properties:

The first.href property links to the first page of resources
The next.href property links to the next page of resources (included for all pages except for the last page)

Use query parameters to page through your available resources and retrieve a subset of objects. To retrieve the first page of results, make the request without specifying a start query parameter. If the results cannot fit on the first page, the response will include a next property, whose value can then be specified as the start parameter when making the next page request. Each page of results is based on the resources that exist at the time of each paginated request, and therefore may include resources that did not exist when the first request was made. The last page of results will not include a next property.

When you're retrieving a subset of objects:

You must add the version and generation query parameters to the href value before you make the request
You may use the value of first.href to retrieve the first page of resources in the requested sort order and with the requested filters
You may use the value of next.href to retrieve the next page of resources in the requested sort order and with the requested filters
You may not change the requested filters across page retrievals
You may not add a sort query parameter to the href value (sort order is set by the first paginated list request)
You may modify the limit in the href value to limit the number of resources to return, per page, in a paginated list operation
You may not change the path segments of the request (that is, anything before the ? in the href value)

List the first five keys: .../keys?limit=5

List the first five keys on the next page: .../keys?limit=5&start=9d5a91a3e2cbd233b5a5b33436855ed1

The next value comes from the previous response's start value, which is a link. Here's the href from the response of the first page:

"href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs?limit=1&start=r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217"

Use the start value r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217 in your next call to fetch page 2:

next := "r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217"
	listVpcsOptions := &vpcv1.ListVpcsOptions{
		Limit: core.Int64Ptr(1),
		Start: &next,
	}
	vpcs, _, err := vpcService.ListVpcs(listVpcsOptions)

The next value comes from the previous response's start value, which is a link. Here's the href from the response of the first page:

"href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs?limit=1&start=r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217"

Use the start value r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217 in your next call to fetch page 2:

ListVpcsOptions listVpcsOptions = new ListVpcsOptions.Builder()
.start("r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217")
.limit(Long.valueOf("10"))
.build();
Response<VPCCollection> response = service.listVpcs(listVpcsOptions).execute();
VPCCollection vpcCollectionResult = response.getResult();

The next value comes from the previous response's start value, which is a link. Here's the href from the response of the first page:

"href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs?limit=1&start=r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217"

Copy the start value r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217 to the clipboard, and use that value in your next call to fetch page 2:

      const listVpcsResult = vpcService.listVpcs({
          start: 'r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217',
          limit: 10,
        });

The next value comes from the previous response's start value, which is a link. Here's the href from the response of the first page:

"href": "https://us-south.iaas.cloud.ibm.com/v1/vpcs?limit=1&start=r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217"

Use the start value r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217 in your next call to fetch page 2:

    next = response.get_result()['next']
try:
    response = service.list_vpcs(start="r134-fe06d70f-ec6c-4451-b0a2-37b6ec91a217", limit=1).get_result()['vpcs']
except ApiException as e:
    print("List VPC failed with status code " + str(e.code) + ": " + e.message)

Response model properties

Certain properties are included in API responses for all customer-created VPC resources. The created_at value is a timestamp that matches when the resource became visible through calls to the IBM Cloud VPC API.

Generation

To use the IBM Cloud VPC infrastructure, send the generation=2 query parameter with every API request.

Example: Create a VPC

POST /v1/vpcs?generation=2

Variables

Consider storing frequently used values (such as the API service URL, authorization token, API version, and other resource identifiers) in variables.

The following topics contain information on setting variables:

Example of storing the us-south service URL in a variable:

vpc_api_endpoint=https://us-south.iaas.cloud.ibm.com

Resources

The VPC API is structured around resources of various types, such as block storage volumes (called "volumes" in the API), and virtual server instances (called "instances" in the API). Each resource consists of a set of properties and supports a set of operations, such as updating some of its property values, or deleting the resource. Certain complex resources also have child resources. For example, the instance resource has one or more volume attachment child resources, with each volume attachment associating the instance with a volume it uses. As with other resources, child resources also have a set of properties and a set of operations, which can be performed on the child resource. Child resources can also have their own child resources.

There is a hierarchical relationship between a resource and its child resources, which is reflected in VPC's API path hierarchy. For example, the API path to retrieve a volume attachment is GET /instances/{instance_id}/volume_attachments/{id}, reflecting that every volume attachment has an instance as its parent resource. This hierarchy is also evident in their lifecycles: deleting an instance will delete all of its child resources, including all of its volume attachments.

Resources that appear in the first segment of the API path hierarchy, such as /instances in the previous example, are sometimes referred to as top-level resources. By convention, top-level resources in the VPC API have crn properties that provide the resource's global Cloud Resource Name (CRN). These CRNs enable top-level resources to be integrated with other IBM Cloud services, such as IAM, billing, and global tagging. For example, because volume attachments are a child resource and do not have their own CRNs, it is not possible to create an IAM policy for a specific volume attachment. Instead, the IAM policies for the parent instance's CRN control access to its volume attachments.

In many situations, the distinction between a top-level resource and a child resource is not important, and the term "resource" is often used to refer to either type of resource.

Resource modeling

Each resource type in the VPC API is represented by a handful of data models, which tailor the resource's properties to the operation being performed:

Prototype model : Used in the request body when creating a resource with POST.

Base model : Returned in the response body when retrieving a resource with GET. This model is also returned in the response body from many other operations, such as when creating a resource.

Patch model : Used in the request body when updating a resource with PATCH.

Identity model : Used when identifying a resource in a request body.

Reference model : Used when identifying a resource in a response body.

Models go hand in hand with objects. An object is an instantiation of a model. For example, POST /instances requires a request body that adheres to the InstancePrototype model, and that request body is an instance prototype object. The response body from POST /instances adheres to the Instance model, and that response body is an instance object. Likewise, the PATCH /instances/{id} request body is an InstancePatch object, and the response body is an Instance object.

In the VPC API, resources are often associated with other resources. When creating an association with a resource, that resource's identity model is used. For example, POST /instances/{id}/volume_attachments, which creates a new volume attachment, expects a VolumeAttachmentPrototype object. That object includes a volume property (VolumeIdentity model) that identifies the volume to attach. As a convenience, some resources have multiple ways to identify them, such as volume.crn, volume.id or volume.href in this scenario.

For an association to succeed, the caller's IAM policies must permit the caller to operate on the identified resource. Additionally, the identified resource must be in the caller's account unless a specific property documents an exception.

To ensure predictable behavior, mutable properties, such as a resource's mutable name, are never included in identity models.

When a resource is retrieved, its association with another resource is shown using that resource's reference model. Continuing the previous example, GET /instances/{instance_id}/volume_attachments/{id} returns a VolumeAttachment object, which includes a volume property (VolumeReference model). In addition to including the identifiers that were present in the VolumeIdentity model (volume.crn, volume.id, and volume.href), it also includes its volume.name, and an optional volume.deleted property, which indicates that the resource no longer exists.

Many reference models also include a resource_type property, which is essential in polymorphic contexts. For example, the floating IP resource (FloatingIP model) includes a target property, which is a oneOf that can refer to a NetworkInterfaceReference or a PublicGatewayReference depending on the way the floating IP resource was created. Further, new types of floating IP targets might be introduced in the future. A client that calls GET /floating_ips/{id} can check the value of target.resource_type to determine if target refers to a network interface resource, a public gateway resource, or another resource type that was introduced after the client was developed.

The properties in a resource's identity and reference models are not subject to that resource's IAM policies. For example, although the volume property included in the response from GET /instances/{instance_id}/volume_attachments/{id} included identifying information about the volume, such as its name and id, the caller did not need an IAM policy to read the volume. This design facilitates adhering to least privilege, because the caller can understand the associations a resource has with other resources without having to be granted access to see the specifics of the associated resources. However, because of this design, it's important to never place sensitive information in a resource's name.

Resource names

VPC resource names adhere to a common regular expression that:

Forbids uppercase characters
Forbids trailing dashes
Reserves leading dashes for system use
Has a name length of 1 - 63 characters
Allows leading digits for system-owned resources (and, eventually, for all resources)
- On a request, the permitted regex is ^([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$.
  
  Resources that do not yet allow leading digits use ^([a-z]|[a-z][-a-z0-9]*[a-z0-9])$.
- On a response, the possible regex is ^-?([a-z]|[a-z][-a-z0-9]*[a-z0-9]|[0-9][-a-z0-9]*([a-z]|[-a-z][-a-z0-9]*[a-z0-9]))$.

Resource namespaces are per resource type and per account. For example, a volume and a server in the same availability zone (AZ) and account can both be named b, and two accounts can both contain a volume that is named b in the same AZ.

For a resource type within an account:

If the resource is scoped within a parent resource, names must be unique within that parent resource.
If the resource is scoped within a VPC, names must be unique within that VPC.
If the resource is regional (or smaller), names must be regionally unique.

If a resource's namespace can contain both customer-created and IBM-created resources, all IBM-created resources (such as IBM-provided images) begin with ibm-. Customers are unable to create resources with the prefix ibm-.

Resource names that begin with a hyphen (-) are reserved for system use and are sometimes used in place of user-defined names. For example, names included with references to deleted resources are prefixed with -deleted-.

If you don't name a resource during resource creation, the system automatically generates a resource name.

Deleted resources

In some responses, embedded resource references may refer to resources that have been deleted. This possibility is noted in contexts where it's expected. Rarely, references to deleted resources may also appear when the system cannot resolve a conflict between concurrent requests.

The presence of a deleted property can be used to determine that a reference is to a deleted resource. The deleted property contains an object with a more_info link to relevant documentation.

As shown in the example, references to deleted resources will have a name prefixed with -deleted- and suffixed with a value to ensure the resource remains unique within its namespace, even if its user-defined name has been reused. This name should not be parsed for information and may not contain any part of the original user-defined name.

Deleted resource reference example:

{
  "name": "-deleted-e1b7144d1645",
  "href": "https://us-south.iaas.cloud.ibm.com/v1/volumes/b6b9395e-6a4d-4291-b824-e1b7144d1645",
  "crn": "crn:[...]",
  "deleted": {
    "more_info": "https://cloud.ibm.com/apidocs/vpc#deleted-resources"
  }
}

Remote resources

In some responses, embedded resource references may refer to resources that are in another region, in another account, or in both another region and another account. If a given reference can be remote, the specification will include a remote property, which can contain account and region child properties, which identify the remote account and remote region for the resource, respectively.

The remote reference shown in the example shows a source image that is both in a different account, and in a region (us-south) that is different from the region being called (us-east). Because the resource has no representation in the region being called, the href for the resource refers to its native region (us-south.iaas.cloud.ibm.com). In contrast, because the remote.region has a representation in the region being called, the remote.region.href refers to the called region (us-east.iaas.cloud.ibm.com).

Remote resource reference example:

{
  "crn": "crn:v1:bluemix:public:is:us-south:a/02828f9c8fd74b73859d371a406af2a1::image:72b27b5c-f4b0-48bb-b954-5becc7c1dcb8",
  "id": "72b27b5c-f4b0-48bb-b954-5becc7c1dcb8",
  "href": "https://us-south.iaas.cloud.ibm.com/v1/images/72b27b5c-f4b0-48bb-b954-5becc7c1dcb8",
  "name": "my-image",
  "remote": {
    "account": {
      "id": "02828f9c8fd74b73859d371a406af2a1",
      "resource_type": "account"
    },
    "region": {
       "href": "https://us-east.iaas.cloud.ibm.com/v1/regions/us-south",
       "name": "us-south",
       "resource_type": "region"
    }
  }
}

When authoring clients that operate on remote references, bear the following in mind:

The resource may have the same name as another local resource, which it may have no relationship to.
Mutable information, such as its name and whether it has been deleted, may not be current.
The resource cannot be directly accessed and may not be accessible at all. For example, attempting to retrieve the example resource using GET /v1/images/72b27b5c-f4b0-48bb-b954-5becc7c1dcb8 results in 404 because the resource is in another account. However, if the resource had been in the same account, but still in a different region, the GET method would result in a 301 Moved Permanently, allowing clients that support redirects to retrieve the resource from its native region.

As discussed in Resources, reference models are not subject to the resource's IAM policies. Therefore, even if the IAM policy that allowed the remote reference to be established is revoked, any remote references that were previously established may continue to have their name updated. Because of this design, it's important to never place sensitive information in a resource's name.

Resource suspension

Individual resources that violate IBM Cloud® terms of use will be suspended. Potential resources that can be suspended include virtual server instances, VPN gateways and VPN servers.

While a resource is suspended, it cannot be used, modified, or deleted. For example, suspended virtual server instances are powered off, and their configuration may not be changed. Connections to VPN gateways and servers are disabled.

Resources that have been suspended will have a lifecycle_state of suspended and a lifecycle_reasons[].code of resource_suspended_by_provider. For information about restoring a suspended resource, see Resource suspension in VPC Getting Started.

API best practices

To minimize bugs caused by changes, follow these best practices when making an API requests:

When processing values for properties that have been expanded, such as for numeric, array, string, and enumeration values, check for and log unknown values. Optionally halt processing and surface the error, or bypass the resource on which the unexpected property value was encountered.
Catch and log any 4xx or 5xx HTTP status code along with the included trace property
Follow HTTP redirect rules for any 3xx HTTP status code.
Use only the resources and properties that are needed for your client to function.
Do not send any extraneous input in a request.
Specify a fixed value for the API version parameter
Avoid depending on any behavior that is not explicitly documented.

Change log

Important changes to the API, such as additions, updates, and deprecations, are documented in the change log.

Features that require clients to specify a later version date are specifically noted in the change log, along with guidance on how to migrate your client to work with newer versions. See Versioning for more information.

SDK changes are based on API changes. When a new API version is available, the SDK reflects changes in the API.

Related APIs

VPC Metadata | IBM Cloud API Docs