Introduction

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

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 a Cloud IAM token. For more information, see Retrieving an access token programmatically.

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.

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=2019-10-25

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.

For more information, see the API Handbook - Versioning overview.

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.

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.

Methods

List gateways

List all Direct Link gateways in this account. Gateways in other accounts with connections to networks in this account are also returned.

GET /gateways
Request

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

  • curl -X GET \
      https://$DL_ENDPOINT/v1/gateways?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN"
Response

Status Code

  • Successfully retrieved the list of gateways.

No Sample Response

This method does not specify any sample responses.

Create gateway

Creates a Direct Link gateway based on the supplied template.

POST /gateways
Request

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

The Direct Link Gateway template

  • curl -X POST \
      https://$DL_ENDPOINT/v1/gateways?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN" \
      -d '{
        "bgp_asn": 1000,
        "global": true,
        "location_name": "dal09",
        "name": "example-gateway",
        "speed_mbps": 1000,
        "type": "dedicated",
        "cross_connect_router": "LAB-xcr01.dal09",
        "metered": true,
        "carrier_name": "my carrier",
        "customer_name": "my customer"
      }''
Response

Status Code

  • The Direct Link gateway was created successfully.

  • An invalid Direct Link template was provided.

No Sample Response

This method does not specify any sample responses.

Delete gateway

Delete a Direct Link gateway.

DELETE /gateways/{id}
Request

Path Parameters

  • The Direct Link gateway identifier

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

  • curl -X DELETE \
      https://$DL_ENDPOINT/v1/gateways/$GATEWAY_ID?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN"
Response

Status Code

  • The Direct Link gateway was deleted successfully.

  • The gateway could not be deleted as there are virtual connections associated with it. Delete all virtual connections associated with this gateway and retry.

  • A Direct Link gateway with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Get gateway

Retrieve a Direct Link gateway.

GET /gateways/{id}
Request

Path Parameters

  • The Direct Link gateway identifier

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

  • curl -X GET \
      https://$DL_ENDPOINT/v1/gateways/$GATEWAY_ID?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN"
Response

Status Code

  • The Direct Link gateway was retrieved successfully.

  • A Direct Link gateway with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Update gateway

Update a Direct Link gateway.

PATCH /gateways/{id}
Request

Path Parameters

  • The Direct Link gateway identifier

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

The Direct Link gateway patch

  • curl -X PATCH \
      https://$DL_ENDPOINT/v1/gateways/$GATEWAY_ID?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN"
      -d '{
        "name": "new_gateway_name"
        } '
    '
Response

Status Code

  • The Direct Link gateway was updated successfully.

  • The request was invalid.

  • A Direct Link gateway with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Get completion notice

Retrieve a gateway's completion notice.

GET /gateways/{id}/completion_notices
Request

Path Parameters

  • The Direct Link gateway identifier

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

  • curl -X GET \
      https://$DL_ENDPOINT/v1/gateways/$GATEWAY_ID/completion_notices?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN"
Response

Completion Notice

Status Code

  • Completion notice retrieved successfully.

  • The Direct Link completion notice for the specified gateway could not be found.

No Sample Response

This method does not specify any sample responses.

Create completion notice

Upload a gateway's completion notice.

PUT /gateways/{id}/completion_notices
Request

Path Parameters

  • The Direct Link gateway identifier

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

Form Parameters

  • Completion notice PDF file

  • curl -X PUT \
      https://$DL_ENDPOINT/v1/gateways/$GATEWAY_ID/completion_notices?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN" \
      -F "upload=@completion_notice.pdf" \
      -H "Content-Type: multipart/form-data"
Response

Status Code

  • Completion notice upload successful.

  • An invalid Direct Link completion notice request was provided.

  • The Direct Link completion notice for the specified gateway could not be found.

No Sample Response

This method does not specify any sample responses.

Get letter of authorization

Retrieve a gateway's Letter of Authorization.

GET /gateways/{id}/loas
Request

Path Parameters

  • The Direct Link gateway identifier

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

  • curl -X GET \
      https://$DL_ENDPOINT/v1/gateways/$GATEWAY_ID/loas?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN"
Response

Letter of Authorization

Status Code

  • Letter of Authorization retrieved successfully.

  • The Direct Link LOA the specified gateway could not be found.

No Sample Response

This method does not specify any sample responses.

List virtual connections

List a gateway's virtual connections.
For gateway in otheraccount with virtual connections that connect to network in this account. Only virtual connections that connect to this account are returned.

GET /gateways/{gateway_id}/virtual_connections
Request

Path Parameters

  • The Direct Link gateway identifier

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

  • curl -X GET \
      https://$DL_ENDPOINT/v1/gateways/$GATEWAY_ID/virtual_connections?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN"
Response

Status Code

  • The virtual connections were retrieved successfully.

  • The specified virtual connection could not be found.

No Sample Response

This method does not specify any sample responses.

Create virtual connection

Create a virtual connection to the specified network.

POST /gateways/{gateway_id}/virtual_connections
Request

Path Parameters

  • The Direct Link gateway identifier

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

The virtual connection template

  • curl -X POST \
      https://$DL_ENDPOINT/v1/gateways/$GATEWAY_ID/virtual_connections?version=2019-12-13\
      -H "authorization: Bearer $IAM_TOKEN" \
      -d '{
        "type":"vpc",
        "name": "my-example-connection",
        "network_id":"$VPC_CRN"
      }'
      ' 
Response

Status Code

  • The virtual connection was created successfully.

  • An invalid template was provided.

  • The specified gateway could not be found.

No Sample Response

This method does not specify any sample responses.

Delete virtual connection

Delete the virtual connection.

DELETE /gateways/{gateway_id}/virtual_connections/{id}
Request

Path Parameters

  • The Direct Link gateway identifier

  • The virtual connection identifier

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

  • curl -X DELETE \
      https://$DL_ENDPOINT/v1/gateways/$GATEWAY_ID/virtual_connections/$VIRTUAL_CONNECTION_ID?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN"
Response

Status Code

  • The virtual connection was removed successfully.

  • A virtual connection with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Get virtual connection

Retrieve a virtual connection.

GET /gateways/{gateway_id}/virtual_connections/{id}
Request

Path Parameters

  • The Direct Link gateway identifier

  • The virtual connection identifier

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

  • curl -X GET \
      https://$DL_ENDPOINT/v1/gateways/$GATEWAY_ID/virtual_connections/$VIRTUAL_CONNECTION_ID?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN"
Response

Status Code

  • The virtual connection was retrieved successfully.

  • A virtual connection with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

Update virtual connection

Update a virtual connection.

PATCH /gateways/{gateway_id}/virtual_connections/{id}
Request

Path Parameters

  • The Direct Link gateway identifier

  • The virtual connection identifier

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

The virtual connection patch template

  • curl -X PATCH \
      https://$DL_ENDPOINT/v1/gateways/$GATEWAY_ID/virtual_connections/$VIRTUAL_CONNECTION_ID?version=2019-12-13\
      -H "authorization: Bearer $IAM_TOKEN" \
      -d '{
        "name":"new-name"
      }'
      ' 
Response

Status Code

  • The virtual connection was updated successfully.

  • The request was invalid.

  • A virtual connection with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

List available locations

Retrieve the list of valid locations for the specified Direct Link offering.

GET /offering_types/{offering_type}/locations
Request

Path Parameters

  • The Direct Link offering type

    Allowable values: [dedicated]

    Example: dedicated

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

  • curl -X GET \
      https://$DL_ENDPOINT/v1/offering_types/dedicated/locations?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN"
Response

Status Code

  • The Direct Link locations for offering type were retrieved successfully.

  • The Direct Link locations offering type could not be retrieved.

  • A Direct Link locations for the specified offering type could not be found.

No Sample Response

This method does not specify any sample responses.

List routers

Retrieve location specific information.

GET /offering_types/{offering_type}/locations/{name}/cross_connect_routers
Request

Path Parameters

  • The Direct Link offering type

    Allowable values: [dedicated]

    Example: dedicated

  • The name of the Direct Link location

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

  • curl -X GET \
      https://$DL_ENDPOINT/v1/offering_types/dedicated/locations/dal09/cross_connect_routers?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN"
Response

Status Code

  • The location information was retrieved successfully.

  • A location information with the specified identifier could not be found.

No Sample Response

This method does not specify any sample responses.

List speed options

List the available Direct Link speeds.

GET /offering_types/{offering_type}/speeds
Request

Path Parameters

  • The Direct Link offering type

    Allowable values: [dedicated]

    Example: dedicated

Query Parameters

  • Requests the version of the API as a date in the format YYYY-MM-DD. Any date from 2019-12-13 up to the current date may be provided. Specify the current date to request the latest version.

  • curl -X GET \
      https://$DL_ENDPOINT/v1/offering_types/dedicated/speeds?version=2019-12-13 \
      -H "authorization: Bearer $IAM_TOKEN"
Response

Status Code

  • The Direct Link offering speeds were retrieved successfully.

  • The Direct Link offering speeds could not be retrieved for the offering type.

  • A Direct Link offering speed with the specified offering type could not be found.

No Sample Response

This method does not specify any sample responses.