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.
IBM CIS gets you going quickly by establishing defaults for you, which you can change easily using the API or UI. Here are some commonly changed parameters:
- DNS settings: you can use IBM CIS to host your DNS or you can create CNAME records.
- Crypto settings (TLS): the default is flexible mode, which encrypts the connection between your host and the IBM CIS edge server, but does not encrypt the communication between the IBM CIS edge server and origin server.
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
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
{
"success": true,
"errors": [
{}
],
"messages": [
{}
],
"result": {
"zones": [
{
"zone": {
"status": null,
"name": null,
"security": null,
"paused": false
},
"dns_record": {
"count": 0
},
"load_balancer": {
"monitor_count": 0,
"pool_count": 0,
"load_balancer_active_count": 0
},
"caching": {
"edge_cache_ttl": 0,
"cache_browser_ttl": 0,
"development_mode": "off",
"cache_level": "basic"
},
"pagerule": {
"active_count": 0,
"inactive_count": 0
},
"waf": {
"status": null
},
"ssl": {
"mode": null,
"universal_ssl_certificate": "off",
"dedicate_certificate_count": 0,
"custom_upload_certificate_count": 0,
"tls_1_2_only": "on"
},
"plan_details": {
"plan_name": "Standard",
"days_remaining": null
},
"firewall": {
"security_level": "low"
}
}
],
"service_maintenance": {
"start_time": null,
"end_time": null,
"message": null
}
}
}
Methods
List all DNS records.
List all DNS records for a given zone of a service instance.
GET /v1/{crn}/zones/{zone_identifier}/dns_records
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
Zone identifier of the zone for which DNS record is created
Query Parameters
Type of DNS records to display.
Value of name field to filter by.
Value of content field to filter by.
Page number of paginated results.
Default:
1
Maximum number of DNS records per page.
Constraints: value ≥ 5
Default:
20
Field by which to order list of DNS records.
Allowable values: [
type
,name
,content
,ttl
,proxied
]Direction in which to order results [ascending/descending order].
Allowable values: [
asc
,desc
]Whether to match all (all) or atleast one search parameter (any).
Allowable values: [
any
,all
]
curl -X GET \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/dns_records \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx'
Was operation successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
ID
Example:
f1aba936b94213e5b8dca0c0dbf1f9cc
Created date
Example:
2014-01-01T05:20:00.12345Z
Modified date
Example:
2014-01-01T05:20:00.12345Z
Name
Example:
host-1.test-example.com
Type
Possible values: [
A
,AAAA
,CNAME
,NS
,MX
,TXT
,LOC
,SRV
,SPF
,CAA
]Example:
A
Content
Example:
169.154.10.10
Zone ID
Example:
023e105f4ecef8ad9ca31a8372d0c353
Zone name
Example:
test-example.com
Proxiable
Example:
true
Proxied
TTL
Example:
120
Relevant only to MX type records.
Example:
5
Data details for the DNS record. Only for LOC, SRV, CAA records.
result
Statistics of results
Page number
Example:
1
Number of results per page
Example:
2
Number of results
Example:
1
Total number of results
Example:
200
result_info
Status Code
Success
Bad Request
Unauthorized
Forbidden! User has no privilege
Resource not found
Internal server error
{ "result": [ { "id": "58e96913cff39f73d8901a6a4ea07e16", "type": "A", "name": "example.com", "content": "192.168.127.127", "proxiable": true, "proxied": false, "ttl": 3600, "locked": false, "zone_id": "3fefc35e7decadb111dcf85d723a4f20", "zone_name": "example.com", "modified_on": "2018-10-11T13:34:45.189800Z", "created_on": "2018-10-11T13:34:45.189800Z" }, { "id": "0f4740fc36065f8a9343c7ed9445f2a4", "type": "A", "name": "www.example.com", "content": "192.168.127.127", "proxiable": false, "proxied": false, "ttl": 1, "locked": false, "zone_id": "3fefc35e7decadb111dcf85d723a4f20", "zone_name": "example.com", "modified_on": "2018-10-12T06:04:36.533540Z", "created_on": "2018-10-12T06:04:36.533540Z" } ], "success": true, "errors": [], "messages": [] }
Get a DNS record
Get the details of a DNS record for a given zone under a given service instance.
GET /v1/{crn}/zones/{zone_identifier}/dns_records/{dnsrecord_identifier}
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full crn of the service instance
Zone identifier (zone id)
Identifier of DNS record
curl -X GET \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/dns_records/:record_id \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx'
Was operation successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
ID
Example:
f1aba936b94213e5b8dca0c0dbf1f9cc
Created date
Example:
2014-01-01T05:20:00.12345Z
Modified date
Example:
2014-01-01T05:20:00.12345Z
Name
Example:
host-1.test-example.com
Type
Possible values: [
A
,AAAA
,CNAME
,NS
,MX
,TXT
,LOC
,SRV
,SPF
,CAA
]Example:
A
Content
Example:
169.154.10.10
Zone ID
Example:
023e105f4ecef8ad9ca31a8372d0c353
Zone name
Example:
test-example.com
Proxiable
Example:
true
Proxied
TTL
Example:
120
Relevant only to MX type records.
Example:
5
Data details for the DNS record. Only for LOC, SRV, CAA records.
result
Status Code
Success
Bad Request
Unauthorized
Forbidden! User has no privilege
Resource not found
Internal server error
{ "result": { "id": "0f4740fc36065f8a9343c7ed9445f2a4", "type": "A", "name": "www.example.com", "content": "192.168.127.127", "proxiable": false, "proxied": false, "ttl": 1, "locked": false, "zone_id": "3fefc35e7decadb111dcf85d723a4f20", "zone_name": "example.com", "modified_on": "2018-10-12T06:04:36.533540Z", "created_on": "2018-10-12T06:04:36.533540Z" }, "success": true, "errors": [], "messages": [] }
Create a DNS record.
Add a new DNS record for a given zone for a given service instance.
POST /v1/{crn}/zones/{zone_identifier}/dns_records
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full url-encoded cloud resource name (CRN) of resource instance
Zone identifier of the zone for which DNS record is to be created.
DNS record parameters.
Required for all record types except SRV.
Example:
host-1.test-example.com
Type
Allowable values: [
A
,AAAA
,CNAME
,NS
,MX
,TXT
,LOC
,SRV
,SPF
,CAA
]Example:
A
Content
Example:
1.2.3.4
For MX records only
Example:
5
For LOC, SRV and CAA records only
curl -X POST \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/dns_records \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx' -d '{ "name": "www", "type": "A", "content": "192.168.127.127" }'
Was operation successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
ID
Example:
f1aba936b94213e5b8dca0c0dbf1f9cc
Created date
Example:
2014-01-01T05:20:00.12345Z
Modified date
Example:
2014-01-01T05:20:00.12345Z
Name
Example:
host-1.test-example.com
Type
Possible values: [
A
,AAAA
,CNAME
,NS
,MX
,TXT
,LOC
,SRV
,SPF
,CAA
]Example:
A
Content
Example:
169.154.10.10
Zone ID
Example:
023e105f4ecef8ad9ca31a8372d0c353
Zone name
Example:
test-example.com
Proxiable
Example:
true
Proxied
TTL
Example:
120
Relevant only to MX type records.
Example:
5
Data details for the DNS record. Only for LOC, SRV, CAA records.
result
Status Code
Success
Bad Request
Unauthorized
Forbidden! User has no privilege
Resource not found
Internal server error
{ "result": { "id": "0f4740fc36065f8a9343c7ed9445f2a4", "type": "A", "name": "www.example.com", "content": "192.168.127.127", "proxiable": false, "proxied": false, "ttl": 1, "locked": false, "zone_id": "3fefc35e7decadb111dcf85d723a4f20", "zone_name": "example.com", "modified_on": "2018-10-12T06:04:36.533540Z", "created_on": "2018-10-12T06:04:36.533540Z" }, "success": true, "errors": [], "messages": [] }
Update a DNS record
Update an existing DNS record for a given zone under a given service instance.
PUT /v1/{crn}/zones/{zone_identifier}/dns_records/{dnsrecord_identifier}
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full crn of the service instance
Zone identifier (zone id)
Identifier of DNS record
Type
Allowable values: [
A
,AAAA
,CNAME
,NS
,MX
,TXT
,LOC
,SRV
,SPF
,CAA
]Example:
A
Required for all record types except SRV.
Example:
host-1.test-example.com
Content
Example:
1.2.3.4
For MX records only
Example:
5
Proxied
For LOC, SRV and CAA records only
curl -X PUT \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/dns_records/:record_id \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx' -d '{ "name": "www", "type": "A", "content": "192.168.127.128" }'
Was operation successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
ID
Example:
f1aba936b94213e5b8dca0c0dbf1f9cc
Created date
Example:
2014-01-01T05:20:00.12345Z
Modified date
Example:
2014-01-01T05:20:00.12345Z
Name
Example:
host-1.test-example.com
Type
Possible values: [
A
,AAAA
,CNAME
,NS
,MX
,TXT
,LOC
,SRV
,SPF
,CAA
]Example:
A
Content
Example:
169.154.10.10
Zone ID
Example:
023e105f4ecef8ad9ca31a8372d0c353
Zone name
Example:
test-example.com
Proxiable
Example:
true
Proxied
TTL
Example:
120
Relevant only to MX type records.
Example:
5
Data details for the DNS record. Only for LOC, SRV, CAA records.
result
Status Code
Success
Bad Request
Unauthorized
Forbidden! User has no privilege
Resource not found
Internal server error
{ "result": { "id": "0f4740fc36065f8a9343c7ed9445f2a4", "type": "A", "name": "www.example.com", "content": "192.168.127.128", "proxiable": false, "proxied": false, "ttl": 1, "locked": false, "zone_id": "3fefc35e7decadb111dcf85d723a4f20", "zone_name": "example.com", "modified_on": "2018-10-12T06:04:36.533540Z", "created_on": "2018-10-12T06:04:36.533540Z" }, "success": true, "errors": [], "messages": [] }
Delete a DNS record.
Delete a DNS record given its id.
DELETE /v1/{crn}/zones/{zone_identifier}/dns_records/{dnsrecord_identifier}
Custom Headers
IBM Cloud user IAM token
Path Parameters
Full crn of the service instance
Identifier of zone (zone id) whose DNS record is to be deleted
Identifier of DNS record
curl -X DELETE \ https://api.cis.cloud.ibm.com/v1/:crn/zones/:zone_id/dns_records/:record_id \ -H 'content-type: application/json' \ -H 'accept: application/json' \ -H 'x-auth-user-token: Bearer xxxxxx'
Was operation successful
Example:
true
Array of errors encountered
Array of messages returned
Container for response information
ID
Example:
f1aba936b94213e5b8dca0c0dbf1f9cc
result
Status Code
Success
Bad Request
Unauthorized
Forbidden! User has no privilege
Resource not found
Internal server error
{ "result": { "id": "0f4740fc36065f8a9343c7ed9445f2a4" }, "success": true, "errors": [], "messages": [] }