Introduction

IBM Cloud Direct Link Connect is a multi-tenant service that allows customers to connect their on-premises networks to their IBM Cloud private networks. This "Provider API" allows partners to create and manage Direct Link Connect gateways in customer' IBM Cloud accounts, providing a seamless, integrated experience. This API supports Direct Link Connect gateways that can be connected to the Virtual Private Cloud (VPC) infrastructure as well as the "Classic" SoftLayer infrastructure supported by the existing Direct Link on Classic API. Direct Link can also connect to IBM Cloud transit gateways.

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

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-provider</artifactId>
    <version>X.X.X</version>
</dependency>

Gradle:

compile 'com.ibm.cloud:direct-link-provider:X.X.X'

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

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

It is assumed that the IBM partner has worked with IBM Cloud Direct Link Offering Management (OM) to onboard to the IBM Cloud platform. This includes business level agreements, provisioning NNIs at various locations, defining port labels, and so on. After this process is completed, partners can request access to the Provider API, which requires the completion of a few simple steps.

Setting up a service identity for Provider API

Create an IBM Cloud account. If you have one already, you can reuse it.
Create a Service ID in this account. Then, share this Service ID with IBM. In the UI, right-click the Service ID link (for example, ServiceId-...) and copy the URL, which includes the ID. You can share the full URL, or just the Service ID.

IBM associates the Direct Link Connect offering with your Service ID when processing Provider API invocations.
Generate an API key for the Service ID.

Provider API authentication

The IBM Cloud Direct Link Provider API uses an Identity and Access Management (IAM) access token passed via the "Authorization" header. This mechanism is described in the following documents in detail:

Generating an IBM Cloud IAM token by using an API key
Invoking IBM Cloud service APIs

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.

For more information, see Authentication with the SDK.

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

IamAuthenticator authenticator = new IamAuthenticator("{apikey}");
DirectLinkProvider directLinkProvider = new DirectLinkProvider("{version}", "{serviceName}",authenticator);

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

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

const directLinkProviderV2 = new DirectLinkProviderV2({
  authenticator: new IamAuthenticator({
    apikey: '{apikey}'
  }),
  version: '${version}',
});

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

from ibm_cloud_networking_services import DirectLinkProviderV2
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')
direct_link_provider = DirectLinkProviderV2(
    version='{version}',
    authenticator=authenticator
)

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

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

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

  options := &directlinkproviderv2.DirectLinkProviderV2Options{
    Version: "{version}",
    Authenticator: authenticator,
  }

  directLinkProvider, directLinkProviderErr := directlinkproviderv2.NewDirectLinkProviderV2UsingExternalConfig(options)

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

API endpoint

https://directlink.cloud.ibm.com

Versioning

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

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

Best practices

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

Dedicate an account for Provider APIs. Do not use this account for any other purpose.
Use an organizational identity as the owner of this account instead of the identity of an individual employee.
Use IBM Cloud IAM to restrict access to the account, especially the Service ID and its API key on an as-needed basis. For more information, see Managing your account, resources, and access.
Safeguard your API key using your organization's security best practices. You might consider using an IBM Cloud service, such as Key Protect for this purpose.
Replace your API key periodically (ideally at least one time every quarter). Delete the old key after a new one is generated.

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 | Invalid 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. |

Direct Link Provider | IBM Cloud API Docs