Domains

Domain resources are domain names that you have purchased from a domain name registrar that you are managing through the CloudsFor DNS interface.

This resource establishes top-level control over each domain. Actions that affect individual domain records should be taken on the [Domain Records] resource.

Attribute Type Description
name number
The name of the domain itself. This should follow
the standard domain format of domain.TLD. For
instance, example.com is a valid domain name.
ttl number
This value is the time to live for the records on
this domain, in seconds. This defines the time
frame that clients can cache queried information
before a refresh should be requested.
zone_file string
This attribute contains the complete contents of
the zone file for the selected domain. Individual
domain record resources should be used to get more
granular control over records. However, this
attribute can also be used to get information about
the SOA record, which is created automatically and
is not accessible as an individual record resource.

List all Domains

To retrieve a list of all of the domains in your account, send a GET request to /api/v1/domains.

The response will be a JSON object with a key called domains. The value of this will be an array of Domain objects, each of which contain the standard domain attributes:

Attribute Type Description
name number
The name of the domain itself. This should follow
the standard domain format of domain.TLD. For
instance, example.com is a valid domain name.
ttl number
This value is the time to live for the records on
this domain, in seconds. This defines the time
frame that clients can cache queried information
before a refresh should be requested.
zone_file string
This attribute contains the complete contents of
the zone file for the selected domain. Individual
domain record resources should be used to get more
granular control over records. However, this
attribute can also be used to get information about
the SOA record, which is created automatically and
is not accessible as an individual record resource.

cURL Example:

curl -X GET -H 'Content-Type: application/json' -u 'user@example.com:password' "https://cloudsfor.com/api/v1/domains"

Request Headers:

Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response Headers:

content-type: application/json; charset=utf-8
status: 200 OK

Response Body:

{
  "domains": [
    {
      "name": "example.com",
      "ttl": 1800,
      "zone_file": "$ORIGIN example.com.\n$TTL 1800\nexample.com. IN SOA ns1.cloudsfor.com. hostmaster.cloudsfor.com. 1415982609 10800 3600 604800 1800\nexample.com. 1800 IN NS ns1.cloudsfor.com.\nexample.com. 1800 IN NS ns2.cloudsfor.com.\nexample.com. 1800 IN NS ns3.cloudsfor.com.\nexample.com. 1800 IN A 1.2.3.4\n"
    }
  ],
  "links": {
  },
  "meta": {
    "total": 1
  }
}

Create a new Domain

To create a new domain, send a POST request to /api/v1/domains. Set the “name” attribute to the domain name you are adding. Set the “ip_address” attribute to the IP address you want to point the domain to.

Attribute Type Description Required
name string
The domain name to add to the CloudsFor DNS
management interface. The name must be unique in
CloudsFor’s DNS system. The request will fail if
the name has already been taken.
true
ip_address string
This attribute contains the IP address you want the
domain to point to.
true

The response will be a JSON object with a key called domain. The value of this will be an object that contains the standard attributes associated with a domain:

Attribute Type Description
name number
The name of the domain itself. This should follow
the standard domain format of domain.TLD. For
instance, example.com is a valid domain name.
ttl number
This value is the time to live for the records on
this domain, in seconds. This defines the time
frame that clients can cache queried information
before a refresh should be requested.
zone_file string
This attribute contains the complete contents of
the zone file for the selected domain. Individual
domain record resources should be used to get more
granular control over records. However, this
attribute can also be used to get information about
the SOA record, which is created automatically and
is not accessible as an individual record resource.

Keep in mind that, upon creation, the zone_file field will have a value of null until a zone file is generated and propagated through an automatic process on the CloudsFor servers.

cURL Example:

curl -X POST -H 'Content-Type: application/json' -u 'user@example.com:password' -d '{"name":"example.com","ip_address":"1.2.3.4"}' "https://cloudsfor.com/api/v1/domains"

Request Headers:

Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Request Body:

{
  "name": "example.com",
  "ip_address": "1.2.3.4"
}

Response Headers:

content-type: application/json; charset=utf-8
status: 201 Created

Response Body:

{
  "domain": {
    "name": "example.com",
    "ttl": 1800,
    "zone_file": null
  }
}

Retrieve an existing Domain

To get details about a specific domain, send a GET request to /api/v1/domains/$DOMAIN_NAME.

The response will be a JSON object with a key called domain. The value of this will be an object that contains the standard attributes defined for a domain:

Attribute Type Description
name number
The name of the domain itself. This should follow
the standard domain format of domain.TLD. For
instance, example.com is a valid domain name.
ttl number
This value is the time to live for the records on
this domain, in seconds. This defines the time
frame that clients can cache queried information
before a refresh should be requested.
zone_file string
This attribute contains the complete contents of
the zone file for the selected domain. Individual
domain record resources should be used to get more
granular control over records. However, this
attribute can also be used to get information about
the SOA record, which is created automatically and
is not accessible as an individual record resource.

cURL Example:

curl -X GET -H 'Content-Type: application/json' -u 'user@example.com:password' "https://cloudsfor.com/api/v1/domains/example.com"

Request Headers:

Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response Headers:

content-type: application/json; charset=utf-8
status: 200 OK

Response Body:

{
  "domain": {
    "name": "example.com",
    "ttl": 1800,
    "zone_file": "$ORIGIN example.com.\n$TTL 1800\nexample.com. IN SOA ns1.cloudsfor.com. hostmaster.example.com. 1415982611 10800 3600 604800 1800\nexample.com. 1800 IN NS ns1.cloudsfor.com.\nexample.com. 1800 IN NS ns2.cloudsfor.com.\nexample.com. 1800 IN NS ns3.cloudsfor.com.\nexample.com. 1800 IN A 1.2.3.4\n"
  }
}

Delete a Domain

To delete a domain, send a DELETE request to /api/v1/domains/$DOMAIN_NAME.

The domain will be removed from your account and a response status of 204 will be returned. This indicates a successful request with no response body.

cURL Example:

curl -X DELETE -H 'Content-Type: application/json' -u 'user@example.com:password' "https://cloudsfor.com/api/v1/domains/example.com"

Request Headers:

Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response Headers:

status: 204 No Content