Introduction to DNS Services Permitted Networks 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 permitted networks

List the permitted networks for a given DNS zone.

GET /instances/{instance_id}/dnszones/{dnszone_id}/permitted_networks
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/permitted_networks \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx'
    
  • package main
    
    import (
    	"encoding/json"
    	"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}")
    
    	listPermittedNetworkOptions := dnsSvc.NewListPermittedNetworksOptions("5cbc3c1b-021c-4ad7-b9e4-a5dfefdecf85", "example.com:3f84b5dc-8c00-463f-a088-9b4e005ebb84")
    	result, listPermittedNetworkResponse, reqErr := dnsSvc.ListPermittedNetworks(listPermittedNetworkOptions)
    	if reqErr != nil {
    		panic(reqErr)
    	}
    
    	fmt.Println(result.PermittedNetworks)
    	fmt.Println(listPermittedNetworkResponse.String())
    }
    
Response

List permitted networks response.

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • You do not have the correct privileges to perform this action.

  • Resource not found.

  • Internal server error.

Example responses
  • {
      "permitted_networks": [
        {
          "id": "fecd0173-3919-456b-b202-3029dfa1b0f7",
          "created_on": "2019-11-01 06:55:31.434598452 +0000 UTC",
          "modified_on": "2019-11-01 06:55:31.434598452 +0000 UTC",
          "permitted_network": {
            "vpc_crn": "crn:v1:bluemix:public:is:eu-de:a/bcf1865e99742d38d2d5fc3fb80a5496::vpc:6e6cc326-04d1-4c99-a289-efb3ae4193d6"
          },
          "type": "vpc",
          "state": "ACTIVE"
        }
      ]
    }

Create a permitted network

Create a permitted network for a given DNS zone.

POST /instances/{instance_id}/dnszones/{dnszone_id}/permitted_networks
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 permitted network.

  • 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/permitted_networks \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx' \
      -d '{
    	  "permitted_network": {
    		    "vpc_crn": "crn:v1:bluemix:public:is:eu-de:a/bcf1865e99742d38d2d5fc3fb80a5496::vpc:6e6cc326-04d1-4c99-a289-efb3ae4193d6"
    		
    	  }, 
    	  "type": "vpc"
    }'
    
  • package main
    
    import (
    	"encoding/json"
    	"fmt"
    
    	"github.com/IBM/dns-svcs-go-sdk/dnssvcsv1"
    	"github.com/IBM/go-sdk-core/core"
    )
    
    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}")
    
    	createPermittedNetworkOptions := dnsSvc.NewCreatePermittedNetworkOptions("5cbc3c1b-021c-4ad7-b9e4-a5dfefdecf85", "example.com:3f84b5dc-8c00-463f-a088-9b4e005ebb84")
    	permittedNetworkCrn, crnErr := dnsSvc.NewPermittedNetworkVpc("crn:v1:bluemix:public:is:eu-de:a/bcf1865e99742d38d2d5fc3fb80a5496::vpc:6e6cc326-04d1-4c99-a289-efb3ae4193d6")
    	if crnErr != nil {
    		panic(crnErr)
    	}
    	createPermittedNetworkOptions.SetPermittedNetwork(permittedNetworkCrn)
    	createPermittedNetworkOptions.SetType(dnssvcsv1.CreatePermittedNetworkOptions_Type_Vpc)
    	result, createPermittedNetworkResponse, reqErr := dnsSvc.CreatePermittedNetwork(createPermittedNetworkOptions)
    	if reqErr != nil {
    		panic(reqErr)
    	}
    
    	permittednetwork, _ := json.MarshalIndent(result, "", "  ")
    	fmt.Println(string(permittednetwork))
    	fmt.Println(createPermittedNetworkResponse.String())
    }
    
Response

Permitted network details

Status Code

  • Permitted network created successfully.

  • Bad Request

  • Unauthorized

  • You do not have the correct privileges to perform this action.

  • Resource not found.

  • Internal server error.

Example responses
  • {
      "id": "fecd0173-3919-456b-b202-3029dfa1b0f7",
      "created_on": "2019-11-01 06:55:31.434598452 +0000 UTC",
      "modified_on": "2019-11-01 06:55:31.434598452 +0000 UTC",
      "permitted_network": {
        "vpc_crn": "crn:v1:bluemix:public:is:eu-de:a/bcf1865e99742d38d2d5fc3fb80a5496::vpc:6e6cc326-04d1-4c99-a289-efb3ae4193d6"
      },
      "type": "vpc",
      "state": "ACTIVE"
    }

Remove a permitted network

Remove a permitted network

DELETE /instances/{instance_id}/dnszones/{dnszone_id}/permitted_networks/{permitted_network_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 permitted network.

  • 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/permitted_networks/fecd0173-3919-456b-b202-3029dfa1b0f7 \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx'
    
  • package main
    
    import (
    	"encoding/json"
    	"fmt"
    
    	"github.com/IBM/dns-svcs-go-sdk/dnssvcsv1"
    	"github.com/IBM/go-sdk-core/core"
    )
    
    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}")
    
    	deletePermittedNetworkOptions := dnsSvc.NewDeletePermittedNetworkOptions("5cbc3c1b-021c-4ad7-b9e4-a5dfefdecf85", "example.com:3f84b5dc-8c00-463f-a088-9b4e005ebb84", "fecd0173-3919-456b-b202-3029dfa1b0f7")
    	result, deletePermittedNetworkResponse, reqErr := dnsSvc.DeletePermittedNetwork(deletePermittedNetworkOptions)
    	if reqErr != nil {
    		panic(reqErr)
    	}
    
    	permittednetwork, _ := json.MarshalIndent(result, "", "  ")
    	fmt.Println(string(permittednetwork))
    	fmt.Println(deletePermittedNetworkResponse.String())
    }
    
Response

Permitted network details

Status Code

  • The permitted network is pending removal.

  • Bad Request

  • Unauthorized

  • You do not have the correct privileges to perform this action.

  • Resource not found.

  • Internal server error.

Example responses
  • {
      "permitted_networks": [
        {
          "id": "fecd0173-3919-456b-b202-3029dfa1b0f7",
          "created_on": "2019-11-01 06:55:31.434598452 +0000 UTC",
          "modified_on": "2019-11-01 06:55:31.434598452 +0000 UTC",
          "permitted_network": {
            "vpc_crn": "crn:v1:bluemix:public:is:eu-de:a/bcf1865e99742d38d2d5fc3fb80a5496::vpc:6e6cc326-04d1-4c99-a289-efb3ae4193d6"
          },
          "type": "vpc",
          "state": "REMOVAL_IN_PROGRESS"
        }
      ]
    }

Get a permitted network

Get details of a permitted network.

GET /instances/{instance_id}/dnszones/{dnszone_id}/permitted_networks/{permitted_network_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 permitted network.

  • 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/permitted_networks/fecd0173-3919-456b-b202-3029dfa1b0f7 \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer xxxxxx'
    
  • package main
    
    import (
    	"encoding/json"
    	"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}")
    
    	getPermittedNetworkOptions := dnsSvc.NewGetPermittedNetworkOptions("5cbc3c1b-021c-4ad7-b9e4-a5dfefdecf85", "example.com:3f84b5dc-8c00-463f-a088-9b4e005ebb84", "fecd0173-3919-456b-b202-3029dfa1b0f7")
    	result, getPermittedNetworkResponse, reqErr := dnsSvc.GetPermittedNetwork(getPermittedNetworkOptions)
    	if reqErr != nil {
    		panic(reqErr)
    	}
    
    	permittednetwork, _ := json.MarshalIndent(result, "", "  ")
    	fmt.Println(string(permittednetwork))
    	fmt.Println(getPermittedNetworkResponse.String())
    }
    
Response

Permitted network details

Status Code

  • Success

  • Bad Request

  • Unauthorized

  • You do not have the correct privileges to perform this action.

  • Resource not found.

  • Internal server error.

Example responses
  • {
      "id": "fecd0173-3919-456b-b202-3029dfa1b0f7",
      "created_on": "2019-11-01 06:55:31.434598452 +0000 UTC",
      "modified_on": "2019-11-01 06:55:31.434598452 +0000 UTC",
      "permitted_network": {
        "vpc_crn": "crn:v1:bluemix:public:is:eu-de:a/bcf1865e99742d38d2d5fc3fb80a5496::vpc:6e6cc326-04d1-4c99-a289-efb3ae4193d6"
      },
      "type": "vpc",
      "state": "ACTIVE"
    }