Introduction to DNS Services Zones 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

The code examples on this tab use the DNS Services Go SDK.

go get -u github.com/IBM/dns-svcs-go-sdk

GitHub

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.
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.
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 DNS zones

List the DNS zones for a given service instance

GET /instances/{instance_id}/dnszones
Request

Custom Headers

  • Uniquely identifying a request

Path Parameters

  • The unique identifier of a service instance

  • curl -X GET \
      https://api.dns-svcs.cloud.ibm.com/v1/instances/1407a753-a93f-4bb0-9784-bcfc269ee1b3/dnszones \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx'
    
  • package main
    
    import (
    	"fmt"
    
    	"github.com/IBM/go-sdk-core/core"
    	"github.com/IBM/dns-svcs-go-sdk/dnssvcsv1"
    )
    
    func main() {
    	authenticator := &core.IamAuthenticator{
    		ApiKey: "{apikey}",
    	}
    
    	options := &dnssvcsv1.DnsSvcsV1Options{
    		Authenticator: authenticator,
    	}
    
    	dnsSvc, dnsSvcErr = dnssvcsv1.NewDnsSvcsV1(options)
    
    	if dnsSvcErr != nil {
    		panic(dnsSvcErr)
    	}
    
    	dnsSvc.SetServiceURL("{url}")
    
    	listZonesOptions := dnsSvc.NewListDnszonesOptions("2be5d4a7-78f0-4c62-a957-41dc15342777")
    	result, detailedResponse, reqErr := dnsSvc.ListDnszones(listZonesOptions)
    	if reqErr != nil {
    		panic(reqErr)
    	}
    
    	fmt.Println(result.Dnszones)
    	fmt.Println(detailedResponse.String())
    }
    
Response

List DNS zones response

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

Example responses
  • {
      "dnszones": [
        {
          "id": "example.com:252926c6-7d0c-4d37-861a-1faca0041785",
          "created_on": "2019-11-13 07:35:58.380539102 +0000 UTC",
          "modified_on": "2019-11-13 07:35:58.380539102 +0000 UTC",
          "instance_id": "9dd2d990-26cd-4cba-9eb0-d2cb6034ee20",
          "name": "example.com",
          "description": "The DNS zone is used for VPCs in us-east region",
          "state": "PENDING_NETWORK_ADD",
          "label": "us-east"
        }
      ]
    }

Create a DNS zone

Create a DNS zone for a given service instance

POST /instances/{instance_id}/dnszones
Request

Custom Headers

  • Uniquely identifying a request

Path Parameters

  • The unique identifier of a service instance

Create a DNS zone.

  • curl -X POST \
      https://api.dns-svcs.cloud.ibm.com/v1/instances/1407a753-a93f-4bb0-9784-bcfc269ee1b3/dnszones \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx' \
      -d '{
    	  "name": "example.com",
    	  "description": "The DNS zone is used for VPCs in us-east region",
    	  "label": "us-east"
    }'
    
  • package main
    
    import (
    	"fmt"
    
    	"github.com/IBM/go-sdk-core/core"
    	"github.com/IBM/dns-svcs-go-sdk/dnssvcsv1"
    )
    
    func main() {
    	authenticator := &core.IamAuthenticator{
    		ApiKey: "{apikey}",
    	}
    
    	options := &dnssvcsv1.DnsSvcsV1Options{
    		Authenticator: authenticator,
    	}
    
    	dnsSvc, dnsSvcErr = dnssvcsv1.NewDnsSvcsV1(options)
    
    	if dnsSvcErr != nil {
    		panic(dnsSvcErr)
    	}
    
    	dnsSvc.SetServiceURL("{url}")
    
    	createZoneOptions := dnsSvc.NewCreateDnszoneOptions("2be5d4a7-78f0-4c62-a957-41dc15342777", "example.com")
    	createZoneOptions.SetDescription("zone description")
    	createZoneOptions.SetLabel("zone_label")
    	result, createZoneResponse, reqErr := dnsSvc.CreateDnszone(createZoneOptions)
    	if reqErr != nil {
    		panic(reqErr)
    	}
    
    	zone, _ := json.MarshalIndent(result, "", "  ")
    	fmt.Println(string(zone))
    	fmt.Println(createZoneResponse.String())
    }
    
Response

DNS zone details

Status Code

  • DNS zone created successfully.

  • Bad Request

  • Unauthorized

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

Example responses
  • {
      "id": "example.com:252926c6-7d0c-4d37-861a-1faca0041785",
      "created_on": "2019-11-13 07:35:58.380539102 +0000 UTC",
      "modified_on": "2019-11-13 07:35:58.380539102 +0000 UTC",
      "instance_id": "9dd2d990-26cd-4cba-9eb0-d2cb6034ee20",
      "name": "example.com",
      "description": "The DNS zone is used for VPCs in us-east region",
      "state": "PENDING_NETWORK_ADD",
      "label": "us-east"
    }

Delete a DNS zone

Delete a DNS zone

DELETE /instances/{instance_id}/dnszones/{dnszone_id}
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 DELETE \
      https://api.dns-svcs.cloud.ibm.com/v1/instances/2be5d4a7-78f0-4c62-a957-41dc15342777/dnszones/example.com:c775e22a-5db5-4614-9c7e-27db0c8dbc13 \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx'
    
  • package main
    
    import (
    	"fmt"
    
    	"github.com/IBM/go-sdk-core/core"
    	"github.com/IBM/dns-svcs-go-sdk/dnssvcsv1"
    )
    
    func main() {
    	authenticator := &core.IamAuthenticator{
    		ApiKey: "{apikey}",
    	}
    
    	options := &dnssvcsv1.DnsSvcsV1Options{
    		Authenticator: authenticator,
    	}
    
    	dnsSvc, dnsSvcErr = dnssvcsv1.NewDnsSvcsV1(options)
    
    	if dnsSvcErr != nil {
    		panic(dnsSvcErr)
    	}
    
    	dnsSvc.SetServiceURL("{url}")
    
    	deleteZoneOptions := dnsSvc.NewDeleteDnszoneOptions("2be5d4a7-78f0-4c62-a957-41dc15342777", "example.com:c775e22a-5db5-4614-9c7e-27db0c8dbc13")
    	deleteZoneResponse, reqErr := dnsSvc.DeleteDnszone(deleteZoneOptions)
    	if reqErr != nil {
    		panic(reqErr)
    	}
    
    	fmt.Println(deleteZoneResponse.String())
    }
    
Response

Status Code

  • The DNS zone 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 DNS zone

Get details of a DNS zone

GET /instances/{instance_id}/dnszones/{dnszone_id}
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/1407a753-a93f-4bb0-9784-bcfc269ee1b3/dnszones/example.com:2d0f862b-67cc-41f3-b6a2-59860d0aa90e \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx'
    
  • package main
    
    import (
    	"fmt"
    
    	"github.com/IBM/go-sdk-core/core"
    	"github.com/IBM/dns-svcs-go-sdk/dnssvcsv1"
    )
    
    func main() {
    	authenticator := &core.IamAuthenticator{
    		ApiKey: "{apikey}",
    	}
    
    	options := &dnssvcsv1.DnsSvcsV1Options{
    		Authenticator: authenticator,
    	}
    
    	dnsSvc, dnsSvcErr = dnssvcsv1.NewDnsSvcsV1(options)
    
    	if dnsSvcErr != nil {
    		panic(dnsSvcErr)
    	}
    
    	dnsSvc.SetServiceURL("{url}")
    
    	getZoneOptions := dnsSvc.NewGetDnszoneOptions("2be5d4a7-78f0-4c62-a957-41dc15342777", "example.com:c775e22a-5db5-4614-9c7e-27db0c8dbc13")
    	result, getZoneResponse, reqErr := dnsSvc.GetDnszone(getZoneOptions)
    	if reqErr != nil {
    		panic(reqErr)
    	}
    
    	zone, _ := json.MarshalIndent(result, "", "  ")
    	fmt.Println(string(zone))
    	fmt.Println(getZoneResponse.String())
    }
    
Response

DNS zone details

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

Example responses
  • {
      "id": "example.com:252926c6-7d0c-4d37-861a-1faca0041785",
      "created_on": "2019-11-13 07:35:58.380539102 +0000 UTC",
      "modified_on": "2019-11-13 07:35:58.380539102 +0000 UTC",
      "instance_id": "9dd2d990-26cd-4cba-9eb0-d2cb6034ee20",
      "name": "example.com",
      "description": "The DNS zone is used for VPCs in us-east region",
      "state": "PENDING_NETWORK_ADD",
      "label": "us-east"
    }

Update the properties of a DNS zone

Update the properties of a DNS zone.

PATCH /instances/{instance_id}/dnszones/{dnszone_id}
Request

Custom Headers

  • Uniquely identifying a request

Path Parameters

  • The unique identifier of a service instance

  • The unique identifier of a DNS zone

Update a dnszone's properties.

  • curl -X PATCH \
      https://api.dns-svcs.cloud.ibm.com/v1/instances/1407a753-a93f-4bb0-9784-bcfc269ee1b3/dnszones/example.com:2d0f862b-67cc-41f3-b6a2-59860d0aa90e \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx' \
      -d '{
    	  "description": "The DNS zone is used for VPCs in us-east region",
    	  "label": "us-east"
    }'
    
  • package main
    
    import (
    	"fmt"
    
    	"github.com/IBM/go-sdk-core/core"
    	"github.com/IBM/dns-svcs-go-sdk/dnssvcsv1"
    )
    
    func main() {
    	authenticator := &core.IamAuthenticator{
    		ApiKey: "{apikey}",
    	}
    
    	options := &dnssvcsv1.DnsSvcsV1Options{
    		Authenticator: authenticator,
    	}
    
    	dnsSvc, dnsSvcErr = dnssvcsv1.NewDnsSvcsV1(options)
    
    	if dnsSvcErr != nil {
    		panic(dnsSvcErr)
    	}
    
    	dnsSvc.SetServiceURL("{url}")
    
    	updateZoneOptions := dnsSvc.NewUpdateDnszoneOptions("2be5d4a7-78f0-4c62-a957-41dc15342777", "example.com:c775e22a-5db5-4614-9c7e-27db0c8dbc13")
    	updateZoneOptions.SetDescription("zone description")
    	updateZoneOptions.SetLabel("zone_label")
    	result, updateZoneResponse, reqErr := dnsSvc.UpdateDnszone(createZoneOptions)
    	if reqErr != nil {
    		panic(reqErr)
    	}
    
    	zone, _ := json.MarshalIndent(result, "", "  ")
    	fmt.Println(string(zone))
    	fmt.Println(updateZoneResponse.String())
    }
    
Response

DNS zone details

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • Forbidden! User has no privilege

  • Resource not found

  • Internal server error

Example responses
  • {
      "id": "example.com:252926c6-7d0c-4d37-861a-1faca0041785",
      "created_on": "2019-11-13 07:35:58.380539102 +0000 UTC",
      "modified_on": "2019-11-13 08:35:58.380539102 +0000 UTC",
      "instance_id": "9dd2d990-26cd-4cba-9eb0-d2cb6034ee20",
      "name": "example.com",
      "description": "The DNS zone is used for VPCs in us-east region",
      "state": "PENDING_NETWORK_ADD",
      "label": "us-east"
    }