Ceryx logo
Menu
View as Markdown

Routes

Create, read, update and delete the routes that map hostnames to your services.

A route maps a hostname (its source) to a target, with settings for how Ceryx serves it. Routes are identified by their hostname, and the special source $wildcard is the catch-all route for hostnames without one.

List routes

GET/api/routes

Responses

Status Description Body
200 All routes. array of Route

Example

curl http://ceryx:8080/api/routes

Responds with 200:

[
  {
    "source": "app.example.com",
    "target": "http://app:8000",
    "settings": {
      "enforce_https": false,
      "mode": "proxy",
      "certificate_path": null,
      "key_path": null,
      "mtls_require_client_certificate": false,
      "mtls_trusted_ca": null,
      "mtls_verify_depth": null
    }
  }
]

Create or replace a route

POST/api/routes

Creates the route for source, replacing any existing route for it.

Request body

A RouteCreate object.

Field Type Required Description
source string Yes Hostname to match, or $wildcard for the catch-all route.
target string Yes Upstream to proxy or redirect to.
settings RouteSettingsInput No Any subset of the route settings.

Responses

Status Description Body
201 The stored route. Route
400 Missing or invalid input. Error
500 The storage backend failed, or a Ceryx environment variable the request needs has an unusable value (detail names it). Error

Example

curl -X POST http://ceryx:8080/api/routes \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "app.example.com",
    "target": "http://app:8000"
  }'

Responds with 201:

{
  "source": "app.example.com",
  "target": "http://app:8000",
  "settings": {
    "enforce_https": false,
    "mode": "proxy",
    "certificate_path": null,
    "key_path": null,
    "mtls_require_client_certificate": false,
    "mtls_trusted_ca": null,
    "mtls_verify_depth": null
  }
}

Get a route

GET/api/routes/{host}

Path parameters

Name Type Description
host string Route source hostname, or $wildcard for the catch-all route.

Responses

Status Description Body
200 The route. Route
404 No such resource. Error

Example

curl http://ceryx:8080/api/routes/app.example.com

Responds with 200:

{
  "source": "app.example.com",
  "target": "http://app:8000",
  "settings": {
    "enforce_https": false,
    "mode": "proxy",
    "certificate_path": null,
    "key_path": null,
    "mtls_require_client_certificate": false,
    "mtls_trusted_ca": null,
    "mtls_verify_depth": null
  }
}

Update a route

PUT/api/routes/{host}

Updates an existing route. Omitted fields keep their stored values and settings are merged into the stored settings.

Path parameters

Name Type Description
host string Route source hostname, or $wildcard for the catch-all route.

Request body

A RouteUpdate object.

Field Type Required Description
source string No Optional; must equal the host in the URL.
target string No Upstream to proxy or redirect to.
settings RouteSettingsInput No Any subset of the route settings.

Responses

Status Description Body
200 The updated route. Route
400 Missing or invalid input. Error
404 No such resource. Error
500 The storage backend failed, or a Ceryx environment variable the request needs has an unusable value (detail names it). Error

Example

curl -X PUT http://ceryx:8080/api/routes/app.example.com \
  -H 'Content-Type: application/json' \
  -d '{
    "settings": {
      "enforce_https": true
    }
  }'

Responds with 200:

{
  "source": "app.example.com",
  "target": "http://app:8000",
  "settings": {
    "enforce_https": true,
    "mode": "proxy",
    "certificate_path": null,
    "key_path": null,
    "mtls_require_client_certificate": false,
    "mtls_trusted_ca": null,
    "mtls_verify_depth": null
  }
}

Delete a route

DELETE/api/routes/{host}

Idempotent; deleting a missing route also returns 204.

Path parameters

Name Type Description
host string Route source hostname, or $wildcard for the catch-all route.

Responses

Status Description Body
204 Deleted. None
500 The storage backend failed, or a Ceryx environment variable the request needs has an unusable value (detail names it). Error

Example

curl -X DELETE http://ceryx:8080/api/routes/app.example.com

Responds with 204 and no body.

Esc

Type to search the docs.