November 8, 2018

Zone API

  API Reference

     

Retrieve Zones

Retrieves a full list of zones for the account. Zones not accessible with the API key will not be shown.

Example Request

$ curl https://api.nuevocloud.com/1.0/zones -u nc_apikey:

Returned Response

Returns an array of zone settings.


Retrieve Zone Settings

Retrieves all zone settings for the given domain, alias or zone ID.

Example Request

$ curl https://api.nuevocloud.com/1.0/zones/www.example.com -u nc_apikey:

Example Response

{
"active": true,
"aliases": [
"example.com"
],
"browser_cache_ttl": 14400,
"cache_size": 1,
"certificates": [
{
"domains": [
"example.com"
],
"expiration_date": "2019-01-02T18:26:09Z",
"id": "727f6bf9-3c2b-44ee-aa51-cfda68fc00cd",
"issuer": "Let's Encrypt"
},
{
"domains": [
"www.example.com"
],
"expiration_date": "2019-01-02T18:26:09Z",
"id": "e0f39e6c-cd28-4301-a9c1-c564511f33c4",
"issuer": "Let's Encrypt"
}
],
"created_at": "2018-10-04T20:24:30.324913Z",
"development_mode": false,
"domain": "www.example.com",
"edge_cache_ttl": 14400,
"force_tls": true,
"forward_query_string": true,
"hsts_include_subdomains": false,
"hsts_max_age": 0,
"hsts_preload": false,
"https_rewrite": false,
"id": "1f1808337f",
"rewrite_backend_hostname": false,
"servers": [
{
"active": true,
"hostname": "www.example.com",
"id": "8cdc0c08-5bf9-45f4-a9dd-37e12183b9bb",
"port": 443,
"server": "192.0.2.1",
"use_tls": true,
"verify_certificate": false
}
]
}

Returned Fields 

Field Default Description
active true Activate or deactivate a zone. Inactive zones are removed from the edge and will not incur billing charges. Inactive zones will return a 404 Not Found error for all requests.
aliases [] An array of aliases associated with this zone. All aliases will be redirected to the domain for the zone.
browser_cache_ttl 14400 This setting controls the cache headers sent to browsers. The value is the time-to-live (TTL) specified in seconds.
cache_size 1 The size in GB of the dedicated space allocated at each PoP to this zone.
certificates [] An array of certificates for this zone. The default is an empty array, but Let's Encrypt certificates will be added for any domains not covered by another certificate.
certificates.domains   An array of domains covered by this certificate. This value is extracted from the certificate.
certificates.expiration_date   The expiration date of this certificate. This value is extracted from the certificate.
certificates.id   A unique UUID used to refer to this certificate.
certificates.issuer   The CA that issued this certificate. This value is extracted from the certificate.
created_at   The date this zone was created.
development_mode false Enables or disables development mode. This setting disables the edge cache causing all requests to be forwarded to your origin server(s). The cache is not updated while in development mode, so you may need to purge files afterward.
domain   The primary domain for this zone.
edge_cache_ttl 14400 This setting controls the Surrogate-Control cache header used by the edge cache. The value is the time-to-live (TTL) specified in seconds.
force_tls true Redirect all HTTP requests to HTTPS.
forward_query_string true Whether the query string should be forwarded to the origin server(s). When enabled, the query string will also be used for the cache path, meaning the edge will consider requests with different query strings to be different resources.
hsts_include_subdomains false Adds the IncludeSubdomains directive to the HSTS header. This setting has no effect when HSTS is disabled.
hsts_max_age 0 The max-age TTL for the HSTS header. When set to more than 0, the edge server will add an HSTS header with the specified max-age.
hsts_preload false Adds the Preload directive to the HSTS header. This setting has no effect when HSTS is disabled.
https_rewrite false Scan all text resources (HTML, Javascript, CSS, etc) for http://www.example.com and replace with https://www.example.com
id   A unique UUID to identify this zone. This field is generated automatically and cannot be changed.
rewrite_backend_hostname false Scan all text resources (HTML, Javascript, CSS, etc) for the backend server hostname and replace it with the domain for this zone.
servers [] An array of backend servers associated with this zone.
servers.active true Enables or disables this backend server. No requests will be routed to disabled servers.
servers.hostname null An optional hostname for the backend server. If specified, a Host header with the specified hostname will be added to all requests routed to this server.
servers.id   A unique UUID generated to identify this server.
servers.port 80 The port of the HTTP server on the origin server.
servers.server   The IPv4 address or hostname of the origin server. Hostnames will be resolved at the edge and routed to the IPv4 address given by the DNS server.
servers.use_tls false Whether to use TLS when connecting to this origin server.
servers.verify_certificate false When connecting to the origin server with TLS, whether to verify the origin server's certificate is valid. A valid certificate must be issued for the server's hostname by a trusted CA and must not be expired.

Create a Zone

Creates a new zone. A minimum zone definition contains the domain, however a usable zone also needs at least one server. Any settings not specified on creation are set to their default values.

The new zone is returned.

Example Request

$ curl -X POST -d '{ "domain": "www.example.com", "servers": { "server": "192.0.2.1" } }' https://api.nuevocloud.com/1.0/zones -u nc_apikey:

Example Response

{
"active": true,
"aliases": [],
"browser_cache_ttl": 14400,
"cache_size": 1,
"certificates": [],
"created_at": "2018-10-04T20:24:30.324913Z",
"development_mode": false,
"domain": "www.example.com",
"edge_cache_ttl": 14400,
"force_tls": true,
"forward_query_string": true,
"hsts_include_subdomains": false,
"hsts_max_age": 0,
"hsts_preload": false,
"https_rewrite": false,
"id": "1f1808337f",
"rewrite_backend_hostname": false,
"servers": [
{
"active": true,
"hostname": null,
"id": "8cdc0c08-5bf9-45f4-a9dd-37e12183b9bb",
"port": 80,
"server": "192.0.2.1",
"use_tls": false,
"verify_certificate": false
}
]
}

Update a Zone

Updates the settings for a zone.

Aliases, Certificates, and Servers specified in a zone update and added to the zone.

The updated zone is returned

Example Request

$ curl -X PATCH -d '{ "active": false }' https://api.nuevocloud.com/1.0/zones/www.example.com -u nc_apikey:

Example Response

{
"active": false,
"aliases": [],
"browser_cache_ttl": 14400,
"cache_size": 1,
"certificates": [],
"created_at": "2018-10-04T20:24:30.324913Z",
"development_mode": false,
"domain": "www.example.com",
"edge_cache_ttl": 14400,
"force_tls": true,
"forward_query_string": true,
"hsts_include_subdomains": false,
"hsts_max_age": 0,
"hsts_preload": false,
"https_rewrite": false,
"id": "1f1808337f",
"rewrite_backend_hostname": false,
"servers": [
{
"active": true,
"hostname": null,
"id": "8cdc0c08-5bf9-45f4-a9dd-37e12183b9bb",
"port": 80,
"server": "192.0.2.1",
"use_tls": false,
"verify_certificate": false
}
]
}

Delete a Zone

Removes a zone.

Example Request

$ curl -X DELETE https://api.nuevocloud.com/1.0/zones/www.example.com -u nc_apikey:

Example Response

{
"status": "ok"
}