Tunnels

Tunnels and their endpoints are managed under /v1/tunnels: create a tunnel and receive its token, add the endpoints a zone can use as its origin, and read whether the connector is running. What a tunnel is and how to run its connector: CacheGenie Tunnels. A zone uses an endpoint through ORIGIN_TYPE TUNNEL and TUNNEL_ENDPOINT on Zones.

The tunnel object

  • TUNNEL_ID (String): nine upper-case letters and digits. Never changes.
  • NAME (String): 1 to 64 characters.
  • ENABLED (Integer): 1, or 0 while the tunnel is switched off: its connector is refused and its zones answer with an error page.
  • STATE (String): CONNECTED while a connector reports, DISCONNECTED when one has run but has not reported for 90 seconds, NEVER before the first connects (and again after a new token).
  • LOCATION (String): the id of the location the connector is connected to, as the statistics call lists it under NODES. Empty unless CONNECTED.
  • LOCATION_NAME (String): that location's name. Empty unless CONNECTED.
  • CONNECTED_AT (Integer): when the connector last reported, Unix seconds; 0 before it first does, and once it has stopped cleanly.
  • AGENT_VERSION (String): the connector's version, from its last report.
  • ENDPOINT_COUNT (Integer): how many endpoints the tunnel has.
  • CREATED_AT (Integer): when it was made, Unix seconds.

Reading one tunnel adds ENDPOINTS, a list of endpoint objects. The token is never part of the object: it is in two answers only, the create and a new token, as TOKEN.

The endpoint object

  • ENDPOINT_ID (Integer): the id a zone's TUNNEL_ENDPOINT takes.
  • NAME (String): 1 to 64 characters.
  • SCHEME (String): https or http, how the connector talks to the service.
  • HOST (String): the service's address or hostname as seen from where the connector runs. An IPv6 address is returned as it is normally written, without brackets.
  • PORT (Integer): 1 to 65535.
  • TARGET (String): the three together, such as https://192.168.1.5:443. Read only.
  • ZONES (Array): the ids of the zones whose origin it is. Read only.

List tunnels

GET https://api.cachegenie.com/v1/tunnels

Every tunnel on the account as DATA.TUNNELS, with MESSAGE Tunnels returned.

curl https://api.cachegenie.com/v1/tunnels \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "CODE": 200,
  "MESSAGE": "Tunnels returned.",
  "DATA": {
    "TUNNELS": [
      {
        "TUNNEL_ID": "TV83JLCPA",
        "NAME": "Office web server",
        "ENABLED": 1,
        "STATE": "CONNECTED",
        "LOCATION": "alpha1",
        "LOCATION_NAME": "Alpha City, XX",
        "CONNECTED_AT": 1790897840,
        "AGENT_VERSION": "1.0.0",
        "ENDPOINT_COUNT": 1,
        "CREATED_AT": 1790896000
      }
    ]
  }
}

Create a tunnel

POST https://api.cachegenie.com/v1/tunnels
  • NAME (String, required): 1 to 64 characters.
curl -X POST https://api.cachegenie.com/v1/tunnels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"NAME": "Office web server"}'

The answer is 201 with the new tunnel, an empty ENDPOINTS list and its TOKEN, and MESSAGE Tunnel created. TOKEN is in this answer only: keep it, it is not shown again. A missing or unusable name is 400 NAME is required: 1 to 64 characters.

{
  "CODE": 201,
  "MESSAGE":
    "Tunnel created. TOKEN is in this answer only: keep it, it is not shown again.",
  "DATA": {
    "TUNNEL_ID": "TV83JLCPA",
    "NAME": "Office web server",
    "ENABLED": 1,
    "STATE": "NEVER",
    "LOCATION": "",
    "LOCATION_NAME": "",
    "CONNECTED_AT": 0,
    "AGENT_VERSION": "",
    "ENDPOINT_COUNT": 0,
    "CREATED_AT": 1790896000,
    "ENDPOINTS": [],
    "TOKEN": "cgt_2af4b60e31412d74aec655d5fdfd2c05e39b672a595edaa11cf88b99d359e2ac"
  }
}

View a tunnel

GET https://api.cachegenie.com/v1/tunnels/{TUNNEL_ID}

One tunnel with its ENDPOINTS, and MESSAGE Tunnel returned. A tunnel that does not exist or belongs to another account answers 404 Tunnel not found.

Update a tunnel

POST https://api.cachegenie.com/v1/tunnels/{TUNNEL_ID}
  • NAME (String, optional): 1 to 64 characters.
  • ENABLED (Integer, optional): 1 to switch the tunnel on, 0 to switch it off.

A field left out keeps its value. The answer is the tunnel with its ENDPOINTS and MESSAGE Tunnel updated. Refusals are 400: NAME must be 1 to 64 characters. and ENABLED must be 1 or 0.

curl -X POST https://api.cachegenie.com/v1/tunnels/TV83JLCPA \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ENABLED": 0}'

Make a new token

POST https://api.cachegenie.com/v1/tunnels/{TUNNEL_ID}/token

Replaces the token. The old one stops working at once and the connector using it is cut off, so start it again with the new one. The answer is the tunnel with its new TOKEN, and MESSAGE New token made. TOKEN is in this answer only, and the old token has stopped working. No body is needed.

Delete a tunnel

DELETE https://api.cachegenie.com/v1/tunnels/{TUNNEL_ID}

Deletes the tunnel and its endpoints and answers Tunnel deleted. with an empty DATA. While one of its endpoints is a zone's origin the answer is 409 An endpoint of this tunnel is the origin of a zone.: give that zone another origin first.

List endpoints

GET https://api.cachegenie.com/v1/tunnels/{TUNNEL_ID}/endpoints

The tunnel's endpoints as DATA.ENDPOINTS, with MESSAGE Endpoints returned.

{
  "CODE": 200,
  "MESSAGE": "Endpoints returned.",
  "DATA": {
    "ENDPOINTS": [
      {
        "ENDPOINT_ID": 7,
        "NAME": "Web server",
        "SCHEME": "https",
        "HOST": "192.168.1.5",
        "PORT": 443,
        "TARGET": "https://192.168.1.5:443",
        "ZONES": ["AB12CD34E"]
      }
    ]
  }
}

Add an endpoint

POST https://api.cachegenie.com/v1/tunnels/{TUNNEL_ID}/endpoints
  • NAME (String, required): 1 to 64 characters.
  • SCHEME (String, required): https or http.
  • HOST (String, required): an IPv4 or IPv6 address, or a hostname the connector can resolve, such as app.internal or web.
  • PORT (Integer, optional): 1 to 65535. Left out or empty, 443 for https and 80 for http.
curl -X POST https://api.cachegenie.com/v1/tunnels/TV83JLCPA/endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"NAME": "Web server", "SCHEME": "https", "HOST": "192.168.1.5"}'

The answer is 201 with the endpoint object and MESSAGE Endpoint created. The connector picks it up within 30 seconds. Each refusal is a 400:

  • Give the endpoint a name of 1 to 64 characters.
  • Choose http or https: how the connector talks to your service.
  • Enter the host the connector can reach your service at: a hostname such as app.internal, or an address such as 192.168.1.5.
  • The port must be a number from 1 to 65535.

View, update or delete an endpoint

GET https://api.cachegenie.com/v1/tunnels/{TUNNEL_ID}/endpoints/{ENDPOINT_ID}

One endpoint, with MESSAGE Endpoint returned. An id that is not one of the tunnel's answers 404 Endpoint not found.

POST https://api.cachegenie.com/v1/tunnels/{TUNNEL_ID}/endpoints/{ENDPOINT_ID}

NAME, SCHEME, HOST and PORT as above, each optional: a field left out keeps its value. Every zone using the endpoint follows the change. The answer is the endpoint with MESSAGE Endpoint updated., and the refusals are the add's.

DELETE https://api.cachegenie.com/v1/tunnels/{TUNNEL_ID}/endpoints/{ENDPOINT_ID}

Answers Endpoint deleted. with an empty DATA, or 409 This endpoint is the origin of a zone. while a zone uses it.

When a change cannot be confirmed

A change whose answer from our database was lost is 503 The change could not be confirmed: the service is temporarily unavailable. Read the tunnel again before retrying., with Retry-After. It may or may not have been made, so read the tunnel before sending it again: a second create would make a second tunnel, and a second new token would replace the first.

Was this helpful?