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