Gateway API

Use the Gateway API to programmatically manage backends and routing rules.

Add or update a backend

To add or update an existing backend configuration, use the following command:

curl -X POST http://localhost:8080/entity?entityType=GATEWAY_BACKEND \
 -d '{  "name": "sep-3",
        "proxyTo": "http://localhost:8083",
        "active": true,
        "routingGroup": "adhoc"
    }'

Configure external URLs

If the backend URL is different from the proxyTo URL (for example, internal vs. external hostnames) use the optional externalUrl field to override the link displayed in the Active Backends page:

curl -X POST http://localhost:8080/entity?entityType=GATEWAY_BACKEND \
 -d '{  "name": "sep-3",
        "proxyTo": "http://localhost:8083",
        "active": true,
        "routingGroup": "adhoc",
        "externalUrl": "http://localhost:8084"
    }'

Get all backends

To retrieve a list of all configured cluster backends, use the following command:

`curl -X GET http://localhost:8080/entity/GATEWAY_BACKEND`

This returns a JSON array:

[
    {
        "name": "sep-1",
        "proxyTo": "http://localhost:8081",
        "active": true,
        "routingGroup": "adhoc",
        "externalUrl": "http://localhost:8081"
    },
    {
        "name": "sep-2",
        "proxyTo": "http://localhost:8082",
        "active": true,
        "routingGroup": "adhoc",
        "externalUrl": "http://localhost:8082"
    },
    {
        "name": "sep-3",
        "proxyTo": "http://localhost:8083",
        "active": true,
        "routingGroup": "adhoc",
        "externalUrl": "http://localhost:8084"
    }
]

Get active backends

To retrieve a list of all active cluster backends, use the following commands:

curl -X GET http://localhost:8080/gateway/backend/active

This returns a JSON array:

[
    {
        "name": "sep-1",
        "proxyTo": "http://localhost:8081",
        "active": true,
        "routingGroup": "adhoc",
        "externalUrl": "http://localhost:8081"
    }
]

Activate a backend

To enable a backend to receive traffic, use the following command:

curl -X POST http://localhost:8080/gateway/backend/activate/sep-2

Deactivate a backend

To disable a backend from receiving traffic, use the following command:

curl -X POST http://localhost:8080/gateway/backend/deactivate/sep-2

Delete a backend

To permanently remove a backend configuration, use the following command:

curl -X POST -d "sep-3" http://localhost:8080/gateway/backend/modify/delete

Update Routing Rules

For this feature to work with multiple replicas of the Starburst Gateway, you must provide a shared storage that supports file locking for the routing rules file.

To update routing rules programmatically, see the following example command:

curl -X POST http://localhost:8080/webapp/updateRoutingRules \
 -H 'Content-Type: application/json' \
 -d '{  "name": "sep-rule",
        "description": "updated rule description",
        "priority": 0,
        "actions": ["updated action"],
        "condition": "updated condition"
    }'

Starburst Gateway updates rules based on the rule name.

Multiple replicas

When running multiple Starburst Gateway replicas, provide shared storage that supports file locking for the routing rules file.

If you use multiple replicas with local storage, rules become out of sync when you update them.

Disable routing rules UI

To disable specific pages in the Starburst Gateway UI, set the disablePages property:

uiConfiguration:
  disablePages:
    - 'routing-rules'