The purpose of the cache is to decrease the load on Orchestra Central, when Orchestra API connectors such as service point connector and mobile extension are used. It works by storing responses for GET requests in a cache, so that subsequent requests made for the same resource will be returned immediately from the cache, instead of asking Orchestra Central for it.
By default, the API Gateway cache is enabled, but the configuration might need to be changed, depending on scenario.
Visits with a generated checksum are fetched to the API Gateway and stored in the visitsOn BranchCache. When a REST call is made towards the visitOnBranchCache, the API Gateway filters will first verify that the Visit and checksum exist in the cache. If the Visit is not found, the following possibilities exist:
• The Visit has most likely been called and ended. A “404 Not Found” error message, with no text payload is returned.
• The cache is not yet updated (default refresh rate is 1 second). A “404 Not Found” error message, with text payload, containing information about the refresh rate, is returned.
Here is an example where a client requests for information from Orchestra for the first time (no other client has made the request since Orchestra restart, i.e cache is empty):
1. Client (e.g. a mobile app) asks for Visits in a Queue (it is configured to access central through the gateway).
2. Gateway receives the request.
3. Gateway determines that the request is a GET request and that it should be cached.
4. Gateway checks if there is a cached response for the request URI, in this case there is nothing cached.
5. Request is passed on to Orchestra Central, which returns a response.
6. Gateway receives response and stores it in its configured cache for the request URI.
7. Gateway returns the response to client.
When a client (same or another client) makes a request for the same resource, i.e. with an identical request URI, the response is read from the cache instead:
1. Client asks for Visits in a Queue.
2. Gateway receives request.
3. Gateway determines that the request is a GET request and is cacheable.
4. Gateway checks cache for a response and gets a result.
5. Gateway passes on the response to the client.
With the cache configured to store responses, we save a lot of time, as Orchestra Central does not need to process any requests, as long as the response remains in the cache. This can increase throughput a lot, which enables Orchestra to support many more users than what is normally possible which is required when allowing a large number of users to receive frequent updates on information, such as mobile tickets.
The conf folder contains the following gateway and cache configuration files which allow the gateway’s cache to be configured:
• application.yml which contains gateway-wide configurations.
Do not use the tab key, when editing the application.yml file!
• ehcache.xml which is the cache manager’s configuration file, where different cache parameters are set.
The application.yml file contains a cache configuration section that may look as in the following example:
cache:
# by default the cache metrics connector is only accessable from local machine
allowCacheMetricsFromAllHosts: false
# if true, all requests not matching the rules in cacheRoutes will get cached in the default cache
useDefaultCache: true
# name of cache in ehcache configuration
defaultCacheName: request
# define if unique cache is used for URL query parameters.
defaultCacheUniquePerQueryParameter: false
cacheRoutes:
services:
# name of cache in ehcache configuration
cacheName: serviceCache
# REST path pattern matching
match: /services
# defines which zuul routes to apply caching to
routes: mobile_service_v1, mobile_service_v2
# configure if the cache should store a unique value per query parameter string (default false)
uniquePerQueryParameter : false
mobileServices:
cacheName: serviceCache
match: .*
routes: custom_mobile_services
visits:
cacheName: visitInQueueCache
match: /branches/[0-9]+/queues/[0-9]+/visits[/]?
routes: servicepoint_api
events:
cacheName: eventInQueueCache
match: /branches/[0-9]+/visits/[0-9]+/events[/]?
routes: my_visit_last_queue_event
# Details logging if routing fails. This is off by default not to flood logs if orchestra is down
These parameters define whether or not each request’s query parameter should be interpreted as unique. If both these requests should be seen as the same and cached as the same (parameter = false), or if they should be seen as different requests and cached separately (parameter = true), as in the following example:
/rest/servicepoint/branches/?_=1351353151515
/rest/servicepoint/branches/?_=1445246161616
In some cases, when using query parameters to break the cache, this is not wanted, since the result is that the cache has no function at all. However, in some cases, for example when including the visitId in the request, the queries must be seen as unique per query parameter.
The cache section contains configurations for all different caches used by the gateway for caching requests. Each cache definition is mapped to routes that are configured in a section called routes within the main section zuul. These routes define what request paths the caches trigger on. If there is no cache defined for a route, then a default cache is used for all GET requests, unless configuration useDefaultCache has been switched off (i.e. equals false). defaultCacheName refers to the name of the cache defined in configuration file ehcache.xml.
In the example configuration above, the services cache route will trigger for mobile_service_v1 and mobile_service_v2 routes, so e.g. a request for “<gateway host>/rest/mobile/v2/services” will match mobile_service_v2 and the services cache (since “/services” in the URI matches the configuration for services cache). The configuration for this services cache can be found in ehcache.xml in the conf folder, where the cache parameters for this cache can be found under the cache section, where the cache name is serviceCache as specified in the application.yml file, under the cacheRoutes section.
This allows fine-grained configuration for requests, as very specific requests can be given short/long lived caches, depending on what is needed. For example, mobile ticket information should be short lived, but Branch data should live much longer as that does not change very often.
The ehcache.xml file contains some cache definitions that must not be removed as they are required for the GEO request caching feature (see below). The branches and serviceBranches cache definitions must not be removed. The parameters can be changed as needed, however.
The ehcache.xml file also contains a definition called visitsOnBranchCache. It defines the cache interval and it is by default set to 1 second (timeToLiveSeconds). Make sure that you change this parameter, if needed!
1.6.2. GEO Request Caching
The gateway exposes a service at /geo, which allows clients to use mobile extension service location based API calls. This service is needed specifically in the gateway because the location based calls in the mobile extension API require location calculations which are needed to be performed by the gateway for each location based request.
The gateway caches Branches and Services required for these calculations and makes use of the cached data to for example. find out what Branches are nearby for a client.
The Service is accessible at /geo. For example, to find out what Branches are located within 1 km, one would make the following request (example utilizes the “curl” command):
curl -i -X GET "http://localhost:9090/geo/branches?longitude=12.017959999999979&latitude=57.637160000000094&radius=1000" -H "auth-token:d0516eee-a32d-11e5-bf7f-feff819cdc9f"
The gateway will make a request to Orchestra Central the first time this data is accessed (i.e. not yet in cache) to get Branch data and find out what Branches are located within 1000 m. The next time a client requests Branches for a location, the Branch data is accessed from the cache, which is very quick, allowing a large number of clients to make location based requests, without slowing down Orchestra Central, allowing much higher throughput than what is normally possible.
Do not use the tab key, when editing the application.yml file!