Introduction to DNS Services Records API

IBM Cloud DNS Services allow you to:

  • Create zones that are collections for holding domain names
  • Create DNS resource records under these zones
  • Specify access controls used for the DNS resolution of resource records on a zone-wide level

IBM Cloud DNS Services also maintains its own world-wide set of DNS resolvers. Computer machines provisioned under IBM Cloud on an IBM Cloud network can use resource records configured through IBM Cloud DNS Services by querying IBM Cloud DNS Services' resolvers.

API endpoint

https://api.dns-svcs.cloud.ibm.com

API Endpoint

https://api.dns-svcs.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.
204 Success The resource was deleted successfully.
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.
403 Forbidden You are not allowed to make an update for the requesting resource.
404 Not Found The requested resource could not be found or the API route doesn't exist.
405 Method Not Allowed The HTTP method is not allowed on the API route.
409 Conflict You are not allowing to create a duplicated resource or the resource cannot coexists with other types of resource.
500 Internal Server Error An internal error occurred, your request could not be processed at the moment. Wait a few minutes and try again.

Authentication

The Authorization header is required for each API call. This header is the bearer token for the user, which can be retrieved from IAM (for example, using the ibmcloud iam oauth-tokens command).

Methods

List Resource Records

List the Resource Records for a given DNS zone

GET /instances/{instance_id}/dnszones/{dnszone_id}/resource_records
Request

Custom Headers

  • Uniquely identifying a request

Path Parameters

  • The unique identifier of a service instance

  • The unique identifier of a DNS zone

  • curl -X GET \
      https://api.dns-svcs.cloud.ibm.com/v1/instances/5cbc3c1b-021c-4ad7-b9e4-a5dfefdecf85/dnszones/example.com:3f84b5dc-8c00-463f-a088-9b4e005ebb84/resource_records \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx'
    
Response

List Resource Records response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

Example responses
  • {
      "resource_records": [
        {
          "id": "SRV:5365b73c-ce6f-4d6f-ad9f-d9c131b26370",
          "created_on": "2019-11-14 03:29:14.769736249 +0000 UTC",
          "modified_on": "2019-11-14 03:29:14.769736249 +0000 UTC",
          "name": "_sip._udp.test.example.com",
          "type": "SRV",
          "ttl": 120,
          "rdata": {
            "priority": 100,
            "weight": 100,
            "port": 8000,
            "target": "siphost.com"
          },
          "service": "_sip",
          "protocol": "udp"
        }
      ]
    }

Create a resource record

Create a resource record for a given DNS zone

POST /instances/{instance_id}/dnszones/{dnszone_id}/resource_records
Request

Custom Headers

  • Uniquely identifying a request

Path Parameters

  • The unique identifier of a service instance

  • The unique identifier of a DNS zone

Create a resource record.

  • curl -X POST \
      https://api.dns-svcs.cloud.ibm.com/v1/instances/5cbc3c1b-021c-4ad7-b9e4-a5dfefdecf85/dnszones/example.com:3f84b5dc-8c00-463f-a088-9b4e005ebb84/resource_records \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx' \
      -d '{
    	  "rdata": {
          "priority": 100,
          "weight": 100,
          "port": 8000,
          "target": "siphost.com"
        }, 
        "type": "SRV", 
        "name": "test.example.com", 
        "ttl": 120,
        "service": "_sip",
        "protocol": "udp"
    }'
    
Response

Resource record details

Status Code

  • Resource record created successfully.

  • Bad Request

  • Unauthorized

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

Example responses
  • {
      "id": "SRV:5365b73c-ce6f-4d6f-ad9f-d9c131b26370",
      "created_on": "2019-11-14 03:29:14.769736249 +0000 UTC",
      "modified_on": "2019-11-14 03:29:14.769736249 +0000 UTC",
      "name": "_sip._udp.test.example.com",
      "type": "SRV",
      "ttl": 120,
      "rdata": {
        "priority": 100,
        "weight": 100,
        "port": 8000,
        "target": "siphost.com"
      },
      "service": "_sip",
      "protocol": "udp"
    }

Delete a resource record

Delete a resource record

DELETE /instances/{instance_id}/dnszones/{dnszone_id}/resource_records/{record_id}
Request

Custom Headers

  • Uniquely identifying a request

Path Parameters

  • The unique identifier of a service instance

  • The unique identifier of a DNS zone

  • The unique identifier of a resource record

  • curl -X DELETE \
      https://api.dns-svcs.cloud.ibm.com/v1/instances/5cbc3c1b-021c-4ad7-b9e4-a5dfefdecf85/dnszones/example.com:3f84b5dc-8c00-463f-a088-9b4e005ebb84/resource_records/SRV:5365b73c-ce6f-4d6f-ad9f-d9c131b26370 \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx'
    
Response

Status Code

  • The resource record was deleted successfully

  • Bad Request

  • Unauthorized

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

No Sample Response

This method does not specify any sample responses.

Get a resource record

Get details of a resource record

GET /instances/{instance_id}/dnszones/{dnszone_id}/resource_records/{record_id}
Request

Custom Headers

  • Uniquely identifying a request

Path Parameters

  • The unique identifier of a service instance

  • The unique identifier of a DNS zone

  • The unique identifier of a resource record

  • curl -X GET \
      https://api.dns-svcs.cloud.ibm.com/v1/instances/5cbc3c1b-021c-4ad7-b9e4-a5dfefdecf85/dnszones/example.com:3f84b5dc-8c00-463f-a088-9b4e005ebb84/resource_records/SRV:5365b73c-ce6f-4d6f-ad9f-d9c131b26370 \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx'
    
Response

Resource record details

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

Example responses
  • {
      "id": "SRV:5365b73c-ce6f-4d6f-ad9f-d9c131b26370",
      "created_on": "2019-11-14 03:29:14.769736249 +0000 UTC",
      "modified_on": "2019-11-14 03:29:14.769736249 +0000 UTC",
      "name": "_sip._udp.test.example.com",
      "type": "SRV",
      "ttl": 120,
      "rdata": {
        "priority": 100,
        "weight": 100,
        "port": 8000,
        "target": "siphost.com"
      },
      "service": "_sip",
      "protocol": "udp"
    }

Update the properties of a resource record

Update the properties of a resource record.

PUT /instances/{instance_id}/dnszones/{dnszone_id}/resource_records/{record_id}
Request

Custom Headers

  • Uniquely identifying a request

Path Parameters

  • The unique identifier of a service instance

  • The unique identifier of a DNS zone

  • The unique identifier of a resource record

Update a resource record's properties.

  • curl -X PUT \
      https://api.dns-svcs.cloud.ibm.com/v1/instances/5cbc3c1b-021c-4ad7-b9e4-a5dfefdecf85/dnszones/example.com:3f84b5dc-8c00-463f-a088-9b4e005ebb84/resource_records/SRV:5365b73c-ce6f-4d6f-ad9f-d9c131b26370 \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx' \
      -d '{
    	  "rdata": {
          "priority": 100,
          "weight": 100,
          "port": 8000,
          "target": "siphost.com"
        }, 
        "type": "SRV", 
        "name": "test.example.com",
    }'
    
Response

Resource record details

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

Example responses
  • {
      "id": "SRV:5365b73c-ce6f-4d6f-ad9f-d9c131b26370",
      "created_on": "2019-11-14 03:29:14.769736249 +0000 UTC",
      "modified_on": "2019-11-14 04:29:14.769736249 +0000 UTC",
      "name": "_sip._udp.test.example.com",
      "type": "SRV",
      "ttl": 120,
      "rdata": {
        "priority": 100,
        "weight": 100,
        "port": 8000,
        "target": "siphost.com"
      },
      "service": "_sip",
      "protocol": "udp"
    }