A route is the path to one or more API endpoints.

Concepts

Routes are the starting point for configuring Acheron to act as a proxy and apply specific behaviour on top of your API endpoints.

Route Vocabulary

• Path: A path is a relative URL path pattern, possibly a regular expression, that activates a specific route. It is important that a path uniquely identifies a route, otherwise route resolution is non-deterministic.
• Identifier: The identifier is a string, preferably human-readable, that uniquely identifies a route configuration.
• HTTP Methods: A route is valid for a set of HTTP methods, e.g. GET or POST.
• Sensitive Headers: It is possible to specify a number of headers that are sensitive for a route. Acheron removes sensitive headers from a request before proxying it to upstream servers.
• URL: Routes configured with a URL are proxied to the given URL. Routes should either be configured with a URL or a service.
• Service: Routes configured with a service are proxied to one of the instances declared for a service. In such a set up, Acheron works as a load balancer. Service instance configuration and discovery is not yet implemented.

Route Resolution

When a request comes in, Acheron determines the applicable route by looking at the URL. More specifically, it removes the hostname, port and domain name and finds the route in its configuration store whose path pattern matches the URL path.

It is important to note that the request's HTTP method does not take part in route resolution. Nevertheless, any HTTP request matching a route but having the wrong HTTP method is rejected.

Configuration

Create a route by calling the /admin/routes endpoint:

curl -X POST -H "Content-Type: application/json" -d '{
    // JSON parameters
}' "http://localhost:9090/admin/routes"

JSON body parameters:

• id (required): A unique human readable identifier for the route.
• path (required): A relative path pattern that uniquely identifies the route.
• http_methods: The set of HTTP methods that the route supports. The asterisk (*) as an element of the set matches all HTTP methods, i.e. setting this parameter to ['*'] represent all HTTP methods.
• url: The URL Acheron will proxy the requests to. Semantically speaking, this is mutually exclusive with service_id.
• service_id: The logical name of the service whose instances Acheron will proxy the requests to. Semantically speaking, this is mutually exclusive with url.
• keep_prefix: A boolean value telling Acheron whether it should keep the path pattern when proxying requests to the upstream servers.
• retryable: A boolean value telling Acheron to retry proxying requests to configured service instances, when a failure occurs.
• override_sensitive_headers: A boolean value telling Acheron whether it should override the default set of sensitive headers. Sensitive headers are automatically stripped by Spring Cloud. Default sensitive headers are determined by Spring Cloud and include - among other things - the Authorization header. Overriding the sensitive headers effectively means that we get to decide which headers should be automatically removed when proxying the requests to the upstream servers.
• sensitive_headers: When override_sensitive_headers is true, this represents the set of headers that will be stripped when proxying the requests to the upstream servers.

Example for a hypothetical balances API:

curl -X POST -H "Content-Type: application/json" -d '{
    "id": "balances",
    "http_methods": [
      "GET", "POST"
    ],
    "path": "/balances/**",
    "service_id": "balances",
    "url": "http://localhost:10000/balances",
    "keep_prefix": false,
    "retryable": false,
    "override_sensitive_headers": false,
    "sensitive_headers": []
}' "http://localhost:9090/admin/routes"