DNS Records - IBM Cloud API Docs

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

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

{
  "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
    }
  }
}

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"
    }
  ]
}

List all DNS records.

List all DNS records for a given zone of a service instance.

GET /v1/{crn}/zones/{zone_identifier}/dns_records

/v1/{crn}/zones/{zone_identifier}/dns_records

Request

Custom Headers

X-Auth-User-Token
string
IBM Cloud user IAM token

Path Parameters

crn
string
Full url-encoded cloud resource name (CRN) of resource instance
zone_identifier
string
Zone identifier of the zone for which DNS record is created

Query Parameters

type
string
Type of DNS records to display.
name
string
Value of name field to filter by.
content
string
Value of content field to filter by.
page
integer
Page number of paginated results.

Default: 1
per_page
integer
Maximum number of DNS records per page.

Constraints: value ≥ 5
Default: 20
order
string
Field by which to order list of DNS records.

Allowable values: [type,name,content,ttl,proxied]
direction
string
Direction in which to order results [ascending/descending order].

Allowable values: [asc,desc]
match
string
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'
```

Response

Response Body

list_dnsrecords_resp

Status Code

200
Success
400
Bad Request
401
Unauthorized
403
Forbidden! User has no privilege
404
Resource not found
500
Internal server error

Example responses

Status 200

{
  "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": []
}{
  "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}

/v1/{crn}/zones/{zone_identifier}/dns_records/{dnsrecord_identifier}

Request

Custom Headers

X-Auth-User-Token
string
IBM Cloud user IAM token

Path Parameters

crn
string
Full crn of the service instance
zone_identifier
string
Zone identifier (zone id)
dnsrecord_identifier
string
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'
```

Response

Response Body

dnsrecord_resp

Status Code

200
Success
400
Bad Request
401
Unauthorized
403
Forbidden! User has no privilege
404
Resource not found
500
Internal server error

Example responses

Status 200

{
  "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": []
}{
  "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

/v1/{crn}/zones/{zone_identifier}/dns_records

Request

Custom Headers

X-Auth-User-Token
string
IBM Cloud user IAM token

Path Parameters

crn
string
Full url-encoded cloud resource name (CRN) of resource instance
zone_identifier
string
Zone identifier of the zone for which DNS record is to be created.

Request Body

dnsrecord_input

DNS record parameters.

```
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"
}'
```

Response

Response Body

dnsrecord_resp

Status Code

200
Success
400
Bad Request
401
Unauthorized
403
Forbidden! User has no privilege
404
Resource not found
500
Internal server error

Example responses

Status 200

{
  "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": []
}{
  "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}

/v1/{crn}/zones/{zone_identifier}/dns_records/{dnsrecord_identifier}

Request

Custom Headers

X-Auth-User-Token
string
IBM Cloud user IAM token

Path Parameters

crn
string
Full crn of the service instance
zone_identifier
string
Zone identifier (zone id)
dnsrecord_identifier
string
Identifier of DNS record

Request Body

dnsrecord_update_input

```
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"
}'
```

Response

Response Body

dnsrecord_resp

Status Code

200
Success
400
Bad Request
401
Unauthorized
403
Forbidden! User has no privilege
404
Resource not found
500
Internal server error

Example responses

Status 200

{
  "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": []
}{
  "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}

/v1/{crn}/zones/{zone_identifier}/dns_records/{dnsrecord_identifier}

Request

Custom Headers

X-Auth-User-Token
string
IBM Cloud user IAM token

Path Parameters

crn
string
Full crn of the service instance
zone_identifier
string
Identifier of zone (zone id) whose DNS record is to be deleted
dnsrecord_identifier
string
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'
```

Response

Response Body

delete_dnsrecord_resp

Status Code

200
Success
400
Bad Request
401
Unauthorized
403
Forbidden! User has no privilege
404
Resource not found
500
Internal server error

Example responses

{ "result": { "id": "0f4740fc36065f8a9343c7ed9445f2a4" }, "success": true, "errors": [], "messages": [] }

Introduction

API Endpoint

Error handling

Success 200 Example Code

Failure 401 Example Code

Failure 404 Example:

Methods

List all DNS records.

Custom Headers

X-Auth-User-Token

Path Parameters

crn

zone_identifier

Query Parameters

type

name

content

page

per_page

order

direction

match

Response Body

success

errors

messages

result

id

created_on

modified_on

name

type

content

zone_id

zone_name

proxiable

proxied

ttl

priority

data

result_info

page

per_page

count

total_count

Status Code

200

400

401

403

404

500

Get a DNS record

Custom Headers

X-Auth-User-Token

Path Parameters

crn

zone_identifier

dnsrecord_identifier

Response Body

success

errors

messages

result

id

created_on

modified_on

name

type

content

zone_id

zone_name

proxiable

proxied

ttl

priority

data

Status Code

200

400