Introduction

The IBM Cloud® Direct Link API is a RESTful API that allows you to manage your Direct Link resources.

The code examples on this tab use the client library that is provided for Go.

Installation

go get -u github.com/IBM/networking-go-sdk
go get  -u github.com/IBM/go-sdk-core

https://github.com/IBM/networking-go-sdk

The code examples on this tab use the client library that is provided for Java.

Maven

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>direct-link</artifactId>
    <version>X.X.X</version>
</dependency>

The code examples on this tab use the client library that is provided for Node.js.

Installation

npm install ibm-networking-services

https://github.com/IBM/networking-node-sdk

The code examples on this tab use the client library that is provided for Python.

Installation

pip install --upgrade "ibm-cloud-networking-services>=X.X.X"

https://github.com/IBM/networking-python-sdk

Authentication

The IBM Cloud Direct Link API uses Identity and Access Management (IAM) to authenticate requests. Pass a bearer token in an Authorization header.

You can retrieve an access token by first creating an API key, and then exchanging your API key for an IBM Cloud IAM token. For more information, see Retrieving an access token programmatically.

The SDK provides initialization methods for each form of authentication.

Use the API key to have the SDK manage the lifecycle of the access token. The SDK requests an access token, ensures that the access token is valid, and refreshes it if necessary.
Use the access token to manage the lifecycle yourself. You must periodically refresh the token.

IAM authentication. Replace {apikey} and {url} with your service credentials.

curl -u "apikey:{apikey}" -X {request_method} "{url}/{method}"

SDK managing the IAM token. Replace {apikey}, {version}, and {url}.

IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
DirectLink directLink = new DirectLink("{version}", "{serviceName}",authenticator);

// Use only when need to change the endpoint.
// Default endpoint is directlink.cloud.ibm.com
directLink.setServiceUrl("{url}")

SDK managing the IAM token. Replace {apikey}, {version}, and {url}.

const DirectLinkV1 = require('ibm-networking-services/direct-link');
const { IamAuthenticator } = require('ibm-cloud-sdk-core');

const directLinkV1 = new DirectLinkV1({
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
  }),
  version: '{version}',
  // Default is directlink.cloud.ibm.com
  serviceUrl: '{url}',
});

SDK managing the IAM token. Replace {apikey} , {version}, and {url}.

from ibm_cloud_networking_services import DirectLinkV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
direct_link = DirectLinkV1(
    version='{version}',
    authenticator=authenticator
)

## Use only when need to change the endpoint.
## Default endpoint is directlink.cloud.ibm.com
direct_link.set_service_url('{url}')

SDK managing the IAM token. Replace {apikey}, {version}, and {url}.

import (
  "github.com/IBM/go-sdk-core/core"
  "github.com/IBM/networking-go-sdk/directlinkv1"
)

func main() {
  authenticator := &core.IamAuthenticator{
    ApiKey: "{apikey}",
    URL:    "{serviceURL}"
  }

  version := "{version}"
  options := &directlinkv1.DirectLinkV1Options{
    Version: &version,
    Authenticator: authenticator,
    // Default is directlink.cloud.ibm.com
    URL:    "{serviceURL}",
  }

  directLink, directLinkErr := directlinkv1.NewDirectLinkV1UsingExternalConfig(options)

  if directLinkErr != nil {
    panic(directLinkErr)
  }
}

Auditing

You can monitor API activity within your account by using the IBM Cloud Direct Link service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method.

For more information about how to track IBM Cloud Direct Link activity, see Auditing events for IBM Cloud Direct Link.

Authorization

Access management to Direct Link resources is done through Identity and Access Management (IAM). For more information, see Using IAM permissions with Direct Link.

API endpoint

https://directlink.cloud.ibm.com

Use Virtual Private Endpoint (VPE) for VPC to access Direct Link via https://private.directlink.cloud.ibm.com.

Error handling

The Direct Link API uses standard HTTP response codes to indicate whether a method completed successfully. A 2xx response indicates success. A 4xx type response indicates a failure, and a 5xx type response indicates an internal system error.

| HTTP Error Code | Description | Recovery | |-----------------|-----------------------|-----------------------------------------------------------------------------| | 200 | Success | The request was successful. | | 400 | Bad Request | The input parameters in the request body are either incomplete, in the wrong format, or resources are in an incorrect state. See the specific error message for more details. | | 401 | Unauthorized | You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions. | | 403 | Forbidden | The supplied authentication is not authorized to access the requested action. | | 404 | Not Found | The requested resource might not exist, or the supplied authentication is not authorized to access it. See the specific error message for resource details, verify that the specified resource exists, or contact the account owner to check your permissions to view it. | | 500 | Internal Server Error | IBM Cloud API is currently unavailable. Your request might not be processed. Wait a few minutes and try again. If the problem persists, contact IBM Support. |

ErrorResponse

| Name | Description | |----------------------------------------------------------|--------------------------------------------------------------| | code
string | An identifier of the problem.
Possible values: [invalid_field,invalid_header,invalid_method,missing_field,server_error] | | message
string | An explanation of the problem with possible solutions. | | more_info
string | A URL for more information about the solution. | | target
object | Details about the property (type and name) that is the focus of the problem. |

The Java SDK generates an exception for any unsuccessful method invocation. All methods that accept an argument can also throw an IllegalArgumentException.

| Exception | Description | |------------------------------|-----------------------------------------------| | IllegalArgumentException | An invalid argument was passed to the method. |

When the Java SDK receives an error response from the Direct Link service, it generates an exception from the com.ibm.cloud.sdk.core.service.exception package. All service exceptions contain the following fields.

| Field | Description | |----------------|------------------------------------------| | statusCode | The HTTP response code that is returned. | | message | A message that describes the error. |

Example error handling

try {
  // Invoke a Direct Link method
} catch (BadRequestException e) {
  // Handle Bad Request (400) exception
} catch (UnauthorizedException e) {
  // Handle Unauthorized (401) exception
} catch (ForbiddenException e) {
  // Handle Forbidden (403) exception
} catch (NotFoundException e) {
  // Handle Not Found (404) exception
} catch (RequestTooLargeException e) {
  // Handle Request Too Large (413) exception
} catch (InternalServerErrorException e) {
  // Handle Internal Server Error (500) 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());
}

When the Node SDK receives an error response from the Direct Link service, it creates an Error object with information that describes the error that occurred. This error object is passed as the first parameter to the callback function for the method. The contents of the error object are as shown in the following table.

Error

| Field | Description | |-------------|------------------------------------------| | code | The HTTP response code that is returned. | | message | A message that describes the error. |

Example error handling

directLink.method(params)
  .catch(err => {
    console.log('error:', err);
  });

The Python SDK generates an exception for any unsuccessful method invocation. When the Python SDK receives an error response from the Direct Link service, it generates an ApiException with the following fields.

| Field | Description | |-------------|---------------------------------------------------------| | code | The HTTP response code that is returned. | | message | A message that describes the error. | | info | A dictionary of additional information about the error. |

Example error handling

from ibm_cloud_sdk_core.api_exception import ApiException
try:
    # Invoke a Direct Link method
except ApiException as ex:
    print "Method failed with status code " + str(ex.code) + ": " + ex.message

The Go SDK generates an error for any unsuccessful service instantiation and method invocation. You can check for the error immediately. The contents of the error object are as shown in the following table.

Error

| Field | Description | |-------------|------------------------------------------| | code | The HTTP response code that is returned. | | message | A message that describes the error. |

Example error handling

import "github.com/IBM/networking-go-sdk/directlinkv1"

// Instantiate a service
directLink, directLinkErr := directlinkv1.NewDirectLinkV1(options)

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

// Call a method
result, response, responseErr := directLink.methodName(&methodOptions)

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

Versioning

All API requests require a major version in the path (/v1/) and a date-based version as a query parameter in the format version=YYYY-MM-DD.

For example: GET /v1/gateways?version=2020-06-02

Any date-based version from Direct Link GA, up to the current date, is supported. Start development of new applications with the current date as a fixed value. Do not dynamically use the current date as the version for a production application. Instead, use a fixed date-based version that was tested with your application.

Specify the version to use on API requests with the version parameter when you create the service instance. The service uses the API version for the date you specify, or the most recent version before that date. Don't default to the current date. Instead, specify a date that matches a version that is compatible with your app, and don't change it until your app is ready for a later version.

// Mention the correct date for version param
String version = "2020-07-27";

// Instantiate authenticator as mentioned in Authentication
DirectLink directLink = new DirectLink(version, "{serviceName}", "${authenticator}");

const DirectLinkV1 = require('ibm-networking-services/direct-link');

const directLinkV1 = new DirectLinkV1({
  // Instantiate authenticator as mentioned in Authentication
  authenticator: '${authenticator}',
  version: '2020-07-27',  // Mention the correct date for version param
});

from ibm_cloud_networking_services import DirectLinkV1

## Instantiate authenticatior as mentioned in Authentication
direct_link = DirectLinkV1(
    version="2020-07-27", # Mention the correct date for version param
    authenticator=authenticator
)

import (
  "github.com/IBM/networking-go-sdk/directlinkv1"
)

func main() {

  // Mention the correct date for version param
  version := "2020-07-27"

  //Instantiate authenticator as mentioned in Authentication
  options := &directlinkv1.DirectLinkV1Options{
    Version: version,
    Authenticator: authenticator,
  }

  directLink, directLinkErr := directlinkv1.NewDirectLinkV1UsingExternalConfig(options)
}

API changes

API improvements and fixes are documented in the API change log, along with guidance on code updates that are required to use a new date-based version. By design, new features with backward-incompatible changes apply only to version dates on and after the feature's release. Changes that apply to older versions of the API are designed to maintain compatibility with existing applications and code.

Best practices

To minimize regressions from changes, the following best practices are recommended when you call the API:

Log any 4xx or 5xx HTTP status code along with the included trace property.
Follow HTTP redirect rules for any 3xx HTTP status code.
Consume only the resources and properties that are needed for your application to function.
Avoid depending on any behavior that is not explicitly documented.

Direct Link | IBM Cloud API Docs