Getting existing Routes

To retrieve the current routes which are mapped by dispatcher use the following REST endpoint:bash

The received response object is a list of defined routes which looks like this:bash

The response contains the following elements:

• Route: The basic building block of the gateway. It is defined by an id (ROUTE_ID), a destination uri (URI_NAME), a collection of predicates (PREDICATE_NAME), and a collection of filters (FILTER_NAME). A route is matched if the aggregate predicate is true.

• Predicate: This is a Java 8 Function Predicate. The input type is a Spring Framework ServerWebExchange. This lets you match on anything from the HTTP request, such as headers or parameters.

• Filter: These are instances of Spring Framework GatewayFilter that have been constructed with a specific factory. Here, you can modify requests and responses before or after sending the downstream request.

You can find further information in the Examples section below about configuring route definitions with predicates and with filters.

Manually reloading Routes

If it happens that the dispatcher doesn't automatically refreshes its routes, you can also use the following curl request to trigger the refreshing manually:bash

Service Registration Options

Other services can modify their behavior on how to register to Dispatcher. Use the following tags in the discovery configuration of your service (e.g. for Spring Boot applications: spring.cloud.consul.dicovery.tags in application.yaml):

• registerAsYambasContextPath: Add this tag to create routes for the microservice's REST interface paths that match the YAMBAS REST path conventions. This option is especially used for generated microservices to make them transparent to existing SDKs.
  
  

• notRegisterOnGateway: Add this tag to hide the microservice from outside which means it will not be exposed through the gateway and will be only accessible behind the Dispatcher.

Configure CORS Handling

Since Dispatcher version 1.0.1 the following configuration for Cross-Origin Resource Sharing exists as default within the application.yml:

spring:
    cloud:
        gateway:
    	    default-filters:
            - DedupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin
            globalcors:
    	    	corsConfigurations:
    		    	'[/**]':
	    		    	allowedOrigins: "*"
	    			    allowedHeaders: "*"
        				allowedMethods:
        				- GET
    		    		- POST
    	    			- PUT
        				- DELETE
        				- OPTIONS
            discovery:
                locator:
                    enabled: false

This means that by default:

• CORS requests are allowed from requests that originate from any domain for all paths and all headers
  
  

• Duplicate response header values of Access-Control-Allow-Credentials and Access-Control-Allow-Origin will be removed in cases when both the gateway CORS logic and the downstream logic add them.
  The default strategy is set to RETAIN_FIRST (default) which means that the first header value which is found will be taken.
  
  

• Routes are not created based on services registered by the default DiscoveryClient implementation (spring.cloud.gateway.discovery.locator.enabled: false).

Secure your routes with Spring Security and OAuth2

By using OAuth 2.0 protocol, users can grant limited access to their resources on one site to another site without having to share or expose their credentials. In the Dispatcher service we are using OAuth 2.0 protocol and Spring Security to provide the possibility to secure some parts of your applications by forcing authentication.

{baseUrl}/login/oauth2/code/{registrationId}

routes:
  - id: securedApp
    uri: http://localhost:9999
    predicates:
      - Path=/securedApp/**
    filters:
      - TokenRelay=

Create a Route Definition via POST

Sending a POST request to the actuator gateway API is one way to create a route. Be aware that posting a route containing an ID which already exists will overwrite the existing route definition.
This means that if you want to update a route which already have filters or predicates you want to keep, you have to make sure to also add these filters and predicates values to the request data.

The following snippet contains a request skeleton for creating a new route definition:bash

After posting the defined route can be retrieved via GET request like already shown in the Usage section.

... with specific Predicate

In order to get a first working example we will define a predicate for a route to the specific URI http://example.com . The predicate will be set up to match a specific path:bash

After this route is defined every request against the Dispatcher containing a context path started by /example/ will be routed to http://example.com .

For more information about different predicates which can also be set within Dispatcher's application.yml, please refer to Route Predicate Factories.

... with specific Filter

Additionally we will now add a filter to the route definition to manipulate the request which will be routed. In the following example the additional header X-Request-Foo will be added:bash

For more information about the available filters please refer to GatewayFilter Factories.

Configure a Request Rate Limiter

If you want to limit the amount of incoming requests the RequestRateLimiter is the right choice. The current implementation of the Dispatcher service provides you to use the existing RequestRateLimiter of Spring (RequestRateLimiter GatewayFilter Factory).

The internal Spring implementation uses Redis together with a Token Bucket Algorithm. So this means you need a Redis server instance for the RequestRateLimiter. The implementation contains two arguments the replenishRate and the burstCapacity.

The replenishRate is how many requests per second do you want a user to be allowed to do, without any dropped requests. This is the rate that the token bucket is filled.

The burstCapacity is the maximum number of requests a user is allowed to do in a single second. This is the number of tokens the token bucket can hold.

Alternative explanation:

Imagine you are in a video game and your health bar equals the number of request. Then the burstCapacity is the maximum damage per second you can take and the replenishRate is the number of request per second that heals you after you got hurt. Incoming request can only be handled if you have health left.

This means:

• a steady rate is accomplished by setting the same value in replenishRate and burstCapacity

• temporary bursts can be allowed by setting burstCapacity higher than replenishRate, but the time to recover from the burst takes longer

If the limits are reached then the RequestRateLimiter filter will return HTTP 429 - Too Many Requests if a keyResolver was configured properly.

By default, if the KeyResolver does not find a key, requests are always denied with HTTP 403 - Forbidden. You can adjust this behavior by playing around with the spring.cloud.gateway.filter.request-rate-limiter.deny-empty-key ( true or false ) and spring.cloud.gateway.filter.request-rate-limiter.empty-key-status-code properties (please refer to the Spring documentation for that).

Dispatcher 1.1.0 automatically provides the following default KeyResolver implementation which helps you to be able to use the RequestRateLimiter functionality out of the box: java

As soon as this or any other KeyResolver implementation is provided you be able to progress with the setup and configure your RequestRateLimiter.

spring:
  redis:
    host: localhost
    port: 6379