Introduction

IBM Cloud Internet Services (CIS), powered by Cloudflare, provides a fast, highly performant, reliable, and secure internet service for customers running their business on IBM Cloud.

Range is a global TCP Proxy running on CIS edge nodes. Range brings DDoS protection, load balancing, and content acceleration to any TCP-based protocol.

* **Protect TCP ports and protocols from **layer 3 and 4 DDoS** attacks.
* **Reduce the ability of attackers to snoop and steal sensitive data by enabling **TLS encryption**.
* **Integrate with CIS IP Firewall, which allows to block or challenge IP addresses, or entire IP ranges, from reaching your TCP services.
* **Configure load balancers with TCP health checks, failover, and steering policies to dictate where traffic should flow.

Range is available only with Enterprise Plans.

For complete information about establishing and managing an IBM Cloud CIS instance, refer to our customer documentation.

API endpoint

https://api.cis.cloud.ibm.com

API Endpoint

https://api.cis.cloud.ibm.com

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually 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 or in the wrong format. 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 again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access '{namespace}'.
404 Not Found The requested resource could not be found.
408 Request Timeout The connection to the server timed out. Wait a few minutes, then try again.
409 Conflict The entity is already in the requested state.
500 Internal Server Error IBM Cloud Internet Services is currently unavailable. Your request could not be processed. Please wait a few minutes and try again.

Here are some model code examples for error handling in the IBM Cloud Internet Services API:

Success 200 Example Code

200 The API was completed successfully

{
   "result":
   {
        "id": "4f70c3d4f20576b79135b898295e8093",
        "protocol": "tcp/22",
        "dns":
        {
            "type": "CNAME",
            "name": "ssh.example.com"
        },
        "origin_direct":
        [
            "tcp://172.0.2.1:22"
        ],
        "ip_firewall": true,
        "proxy_protocol": true,
        "created_on": "2019-01-09T17:33:09.190606Z",
        "modified_on": "2019-01-09T17:33:09.190606Z"
    },
    "success": true,
    "errors": [],
    "messages": []
}

Failure 401 Example Code

401 Action unauthorized

{
  "trace": "be45687c-57f2-46e8-8717-32b3153a5886",
  "errors": [
    {
      "code": 401,
      "message": "Action is not authorized."
    }
  ]
}

Failure 404 Example:

404 API not found
{
  "trace": "c3c9f6af-a20f-4b73-8e3d-800a9284a07f",
  "errors": [
    {
      "code": null,
      "message": "404 Not Found"
    }
  ]
}

Methods

Get a list of currently existing Range Applications inside a zone.

Get a list of currently existing Range Applications inside a zone.

GET /v1/{crn}/zones/{zone_identifier}/range/apps
Request

Custom Headers

  • IBM Cloud user IAM token

Path Parameters

  • Full url-encoded cloud resource name (CRN) of resource instance

  • zone identifier

Response

Status Code

  • Success

  • Bad Request

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

Example responses

Get the application configuration of a specific application inside a zone.

Get the application configuration of a specific application inside a zone.

GET /v1/{crn}/zones/{zone_identifier}/range/apps/{app_identifier}
Request

Custom Headers

  • IBM Cloud user IAM token

Path Parameters

  • Full url-encoded cloud resource name (CRN) of resource instance

  • zone identifier

  • application identifier

Response

Status Code

  • Success

  • Bad Request

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

Example responses

Create a Range Applications inside a zone.

Create a Range Applications inside a zone.

POST /v1/{crn}/zones/{zone_identifier}/range/apps
Request

Custom Headers

  • IBM Cloud user IAM token

Path Parameters

  • Full url-encoded cloud resource name (CRN) of resource instance

  • zone identifier

create a range app

Response

Status Code

  • Success

  • Bad Request

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

Example responses

Update a specific range application

Update a Range Application inside a zone.

PUT /v1/{crn}/zones/{zone_identifier}/range/apps/{app_identifier}
Request

Custom Headers

  • IBM Cloud user IAM token

Path Parameters

  • Full url-encoded cloud resource name (CRN) of resource instance

  • zone identifier

  • application identifier

update a range app

Response

Status Code

  • Success

  • Bad Request

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

Example responses

Delete the application configuration

Delete a specific application configuration.

DELETE /v1/{crn}/zones/{zone_identifier}/range/apps/{app_identifier}
Request

Custom Headers

  • IBM Cloud user IAM token

Path Parameters

  • Full url-encoded cloud resource name (CRN) of resource instance

  • zone identifier

  • application identifier

Response

Status Code

  • Success

  • Bad Request

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

Example responses