Zones

A zone is one origin with its hostnames and its settings. Five calls create, read, update and delete zones, and every setting a zone has is a field on the same object.

The zone object#

What each setting does at the edge is in Zone settings; the blocking fields are explained in Blocking visitors.

List zones#

Every zone on the account, newest first, as DATA.CDN_ZONES: a paused zone is listed with the rest, and a deleted one is not.

curl https://api.cachegenie.com/v1/cdn \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "CODE": 200,
  "MESSAGE": "Data returned for all CDN Zones for this account.",
  "DATA": {
    "CDN_ZONES": [
      {
        "ID": "AB12CD34E",
        "ZONE_NAME": "video",
        "ORIGIN_URL": "https://origin.example.com",
        "HOST_HEADER": "",
        "ORIGIN_CERTIFICATE": 0,
        "VERIFY_ORIGIN_SSL": 1,
        "ADD_HOST_HEADER": 0,
        "FOLLOW_REDIRECTS": 0,
        "STRIP_COOKIES": 1,
        "BLOCK_ROOT": 0,
        "BLOCK_POST": 0,
        "ADD_CANONICAL_HEADER": 1,
        "ADD_CORS_HEADER": 1,
        "CACHE_EXP": "-1",
        "HOME_POP": "alpha1",
        "HOME_POP_LOCATION": "alpha1",
        "STATUS": "ACTIVE",
        "ORIGIN_TYPE": "STANDARD",
        "S3_BUCKET": "",
        "S3_REGION": "",
        "S3_ADDRESSING": "PATH",
        "S3_ACCESS_KEY": "",
        "S3_SECRET_KEY_SET": 0,
        "TOKEN_AUTH": 0,
        "MAINTENANCE": 0,
        "USAGE_PAUSED": 0,
        "BLOCK_IPS": "",
        "ALLOW_IPS": "",
        "COUNTRIES": "",
        "COUNTRY_MODE": "BLOCK",
        "BLOCK_ASNS": "",
        "BLOCK_TOR": 0,
        "BLOCK_VPN": 0,
        "BLOCK_HOSTING": 0,
        "TUNNEL_ENDPOINT": 0,
        "TUNNEL_MODE": "SITE",
        "TUNNEL_TARGET": "",
        "TIMESTAMP": 1789200000
      }
    ]
  }
}

View a zone#

One zone object, with MESSAGE CDN Zone Data Returned.. A zone that does not exist, is deleted, or belongs to another account answers 404 CDN Zone not found.; a lower-case or malformed id is a 404 too.

Create a zone#

• ZONE_NAMEStringrequired4 to 40 letters and digits. Lower-cased, and refused if an active zone already has it, because it becomes a hostname.
• ORIGIN_URLString unless ORIGIN_TYPE is TUNNELrequiredhttp:// or https://, a hostname or IP address, an optional port and an optional path, which is put in front of the path a viewer asks for. No query string, no credentials, and no hostname that contains cachegenie.com or cg-cdn.com.
• ORIGIN_TYPEStringoptionalSTANDARD (the default), S3, SITE or TUNNEL. See Origin types below for what each needs.
• HOST_HEADERStringoptionala hostname, or empty for none.
• CACHE_EXPStringoptionalone of the values below, sent as a string or as a number. Anything else is refused.
• HOME_POPStringoptionalan active location id, auto, or empty.
• The eight switches, VERIFY_ORIGIN_SSL, ADD_HOST_HEADER, FOLLOW_REDIRECTS, STRIP_COOKIES, BLOCK_ROOT, BLOCK_POST, ADD_CANONICAL_HEADER and ADD_CORS_HEADER: integers, 1 or 0, each optional. A switch left out takes the default in the table above.
• TOKEN_AUTH and MAINTENANCE: integers, optional, 1 to switch on. Both start 0.
• The bucket fields, S3_BUCKET, S3_REGION, S3_ACCESS_KEY and S3_SECRET_KEY: strings, required together when ORIGIN_TYPE is S3; S3_ADDRESSING, PATH or VHOST, is optional and starts as PATH.
• TUNNEL_ENDPOINT, an integer, required when ORIGIN_TYPE is TUNNEL, and TUNNEL_MODE, SITE (the default) or STANDARD, optional.
• The blocking rules, BLOCK_IPS, ALLOW_IPS, COUNTRIES, COUNTRY_MODE and BLOCK_ASNS as strings and BLOCK_TOR, BLOCK_VPN and BLOCK_HOSTING as integers, each optional. See Blocking fields below.

curl -X POST https://api.cachegenie.com/v1/cdn \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ZONE_NAME": "video",
    "ORIGIN_URL": "https://origin.example.com",
    "VERIFY_ORIGIN_SSL": 1,
    "HOME_POP": "alpha1"
  }'

The answer is the new zone object with MESSAGE CDN Zone Created.. Creating a zone also creates its default hostname, video.zone.cg-cdn.com, with SSL on, and mints a signing key. What can go wrong, each a 400:

• Missing required request parameters in JSON Body.: ZONE_NAME or ORIGIN_URL is absent.
• Unable to decode JSON Body.: the body is not JSON.
• Invalid Zone Name., This CDN Zone Name already exists, please try again.
• Invalid Origin URL., Invalid Host Header.
• CACHE_EXP is not one of the Cache Expiration Time values offered for a CDN Zone.
• HOME_POP must be the ID of an active CDN location (see GET /v1/nodes), "auto" to let CacheGenie choose the location nearest your origin, or empty to turn the origin shield off.
• The origin type and blocking messages listed below.

A write that did not go through is 500 Unable to create CDN Zone - Internal Server Error, please try again.

Update a zone#

Every field of the object except ID, ZONE_NAME, STATUS, USAGE_PAUSED, TIMESTAMP, S3_SECRET_KEY_SET, ORIGIN_CERTIFICATE, HOME_POP_LOCATION and TUNNEL_TARGET (send S3_SECRET_KEY to change the secret), each optional. A field left out (or sent as null) keeps its value; an empty string clears HOST_HEADER, HOME_POP and each blocking list. A body of {} is accepted and changes nothing; a body that is not JSON is refused. The answer is the updated object with MESSAGE CDN Zone Updated.; every change reaches every location within about five seconds.

curl -X POST https://api.cachegenie.com/v1/cdn/AB12CD34E \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"CACHE_EXP": "86400", "STRIP_COOKIES": 1}'

The refusals are the create's, with one wording of its own: ORIGIN_URL must start with http:// or https:// and name a hostname or IP address. A zone with an origin certificate keeps an https:// ORIGIN_URL: an http:// one is 400 ORIGIN_URL has to be https:// while the zone has an origin certificate. Revoke it first with DELETE /v1/cdn/{ZONE_ID}/origin-certificate., and 409 when a certificate was created while the call was made. Switching TOKEN_AUTH on when the zone somehow has no key mints one. A write that did not go through is 500 Unable to update CDN Zone - Internal Server Error, please try again.

Delete a zone#

Removes the zone's hostnames and their certificates and marks the zone deleted; its statistics and the month's usage stay, because they are what the month is invoiced on. The answer is CDN Zone Deleted. with an empty DATA. A zone that cannot be deleted answers 400 Unable to delete CDN Zone, CANNOT_DELETE flag is set to TRUE.; a write that did not go through is 500.

Origin types#

STANDARD needs nothing beyond ORIGIN_URL. SITE takes the web server as ORIGIN_URL and, unless the same request sets them itself, starts with ADD_HOST_HEADER 1, FOLLOW_REDIRECTS 0, STRIP_COOKIES 0, BLOCK_ROOT 0, BLOCK_POST 0, ADD_CANONICAL_HEADER 0 and CACHE_EXP "-1"; switching a zone to SITE applies the same defaults to the fields the request did not send, and switching away does not revert them. See Full site origins.

TUNNEL fetches from an endpoint of one of your tunnels (see CacheGenie Tunnels), named by TUNNEL_ENDPOINT, an ENDPOINT_ID from Tunnels. ORIGIN_URL is not sent and reads empty, and HOME_POP is not used. TUNNEL_MODE is SITE to deliver a whole website, with the SITE defaults above, or STANDARD for static files; left out, a new tunnel zone is SITE and an existing one keeps its delivery. Switching a zone to TUNNEL also sets VERIFY_ORIGIN_SSL, FOLLOW_REDIRECTS and ADD_CANONICAL_HEADER to 0 and clears HOME_POP, for the fields the request did not send; VERIFY_ORIGIN_SSL can be switched back on, and then an https service has to present a certificate a public authority issued for the hostname it is asked for. Switching a tunnel zone to another type needs an ORIGIN_URL, and a zone with an origin certificate cannot become a tunnel zone until the certificate is revoked. Each refusal is a 400 unless marked:

• TUNNEL_ENDPOINT is required for a tunnel zone (see GET /v1/tunnels/{TUNNEL_ID}/endpoints).
• Choose the tunnel endpoint this zone fetches from.: TUNNEL_ENDPOINT is not an id.
• Choose how the tunnel's service is delivered: static files, or a full website.
• ORIGIN_URL does not apply to a tunnel zone: its origin is TUNNEL_ENDPOINT.
• HOME_POP is not applicable to a tunnel zone: the tunnel's entry node is its Home PoP.
• ORIGIN_URL is required when a tunnel zone changes to another origin type.
• A tunnel zone takes no origin certificate. Revoke it first with DELETE /v1/cdn/{ZONE_ID}/origin-certificate.
• 404 Tunnel endpoint not found.: the endpoint is not one of yours, or it has just been deleted.

S3 takes the bucket endpoint as ORIGIN_URL and needs S3_BUCKET (3 to 63 lower-case letters, digits, dots and hyphens), S3_REGION (such as eu-west-1, or auto), S3_ACCESS_KEY (8 to 128 characters) and S3_SECRET_KEY (8 to 256); S3_ADDRESSING is PATH unless you send VHOST. On an update an empty S3_SECRET_KEY keeps the stored one; switching to another type clears the bucket, region and keys and puts the addressing back to PATH, and bucket fields sent to a zone that is not S3, with no ORIGIN_TYPE beside them, are ignored. The secret is never returned. See Private bucket origins. Each refusal is a 400:

curl -X POST https://api.cachegenie.com/v1/cdn \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ZONE_NAME": "library",
    "ORIGIN_TYPE": "S3",
    "ORIGIN_URL": "https://s3.eu-west-1.amazonaws.com",
    "S3_BUCKET": "my-video-bucket",
    "S3_REGION": "eu-west-1",
    "S3_ADDRESSING": "PATH",
    "S3_ACCESS_KEY": "AKIAIOSFODNN7EXAMPLE",
    "S3_SECRET_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }'

• Choose an origin type: a standard public origin, a private S3 bucket, a full site, or a CacheGenie Tunnel.
• The bucket name must be 3 to 63 characters using lower case letters, numbers, dots and hyphens, starting and ending with a letter or a number.
• The region must be the one your bucket lives in, such as eu-west-1 or de. Use auto if your provider does not use regions.
• Choose how the bucket is addressed: in the path, or as part of the endpoint host.
• The access key looks wrong. It is 8 to 128 characters and holds no spaces or quotes.
• Enter the secret key for this bucket. It is stored once and never shown again.
• The secret key looks wrong. It is 8 to 256 characters and holds no spaces or quotes.
• With virtual hosted addressing the endpoint must start with the bucket name, for example https://{bucket}.s3.eu-west-1.amazonaws.com. Choose path style instead if your endpoint is the plain one.
• The endpoint already starts with the bucket name, so choose virtual hosted addressing (otherwise the bucket would be asked for twice).

Blocking fields#

The four lists are strings: addresses one per line (a newline in JSON is \n), country codes and AS numbers comma separated. Addresses are normalised on save (host bits cleared, /32 and /128 dropped), AS numbers may be written with or without the AS, and each list is de-duplicated. At most 1,000 entries in each address list and 200 AS numbers. A list left out keeps its value and an empty string clears it; COUNTRY_MODE is BLOCK or ALLOW, and an empty value leaves it as it was. Each refusal is a 400:

• The blocked addresses list is too long: keep it to 1000 entries or fewer. and the same for the always allow list.
• "X" is not an address or a range. Write one per line, either a single address (203.0.113.9 or 2001:db8::1) or a block in CIDR form (203.0.113.0/24 or 2001:db8::/32).
• The AS number list is too long: keep it to 200 entries or fewer.
• "X" is not an AS number. Write them as numbers separated by commas, with or without the AS (16509 or AS16509).
• Choose whether the countries listed are the ones to block or the only ones to serve.
• "X" is not a country code. Use the two letter ISO codes, separated by commas (GB, IE, FR).
• Choose at least one country to serve, or switch back to blocking: serving only the countries on an empty list would refuse everyone.

Cache Expiration values#

CACHE_EXP has to be one of these values, sent as a string or as a number; it is always returned as a string. The label is what the NOC shows.