# 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](/docs/route-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](/docs/api/schemas#route) |

### Example

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

Responds with `200`:

```json
[
  {
    "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](/docs/api/schemas#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](/docs/api/schemas#routesettingsinput) | No | Any subset of the route settings. |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `201` | The stored route. | [Route](/docs/api/schemas#route) |
| `400` | Missing or invalid input. | [Error](/docs/api/schemas#error) |
| `500` | The storage backend failed, or a Ceryx environment variable the request needs has an unusable value (`detail` names it). | [Error](/docs/api/schemas#error) |

### Example

```bash
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`:

```json
{
  "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](/docs/api/schemas#route) |
| `404` | No such resource. | [Error](/docs/api/schemas#error) |

### Example

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

Responds with `200`:

```json
{
  "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](/docs/api/schemas#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](/docs/api/schemas#routesettingsinput) | No | Any subset of the route settings. |

### Responses

| Status | Description | Body |
| --- | --- | --- |
| `200` | The updated route. | [Route](/docs/api/schemas#route) |
| `400` | Missing or invalid input. | [Error](/docs/api/schemas#error) |
| `404` | No such resource. | [Error](/docs/api/schemas#error) |
| `500` | The storage backend failed, or a Ceryx environment variable the request needs has an unusable value (`detail` names it). | [Error](/docs/api/schemas#error) |

### Example

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

Responds with `200`:

```json
{
  "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](/docs/api/schemas#error) |

### Example

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

Responds with `204` and no body.