Changes related to Apiary and Mashery. Also related to LRTs cases and mentions to SwaggerHub.

rest-api-guidelines/execution/caching.md

@@ -2,15 +2,43 @@
 
 Every API implementation **SHOULD** return both the cache expiry information \([`Cache-Control` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)\) and specific resource version information \([`ETag` HTTP Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)\).
 
-## Cache-Control
+The adidas API Gateway – [Kong](https://konghq.com/kong/) offers the cache feature to APIs to be applied to 1 or N endpoints or Consumer. So, cache fetures can be implemented at API Gateway level, upstream/backend service level or both.
+
+## Cache-Control 
 
 Every API implementation's response **SHOULD** include information about cache-ability and cache expiration of the response. For HTTP 1.1 this is achieved using the `Cache-Control` header.
 
+
+### Settings
+
+#### adidas API Gateway
+The configuration of cache in the adidas API Gateway is mainly based on:
+
+- Cacheable HTTP methods
+- When to cache. Response content types, headers to be considered for the cache key, relevant query parameters, etc.
+- Expiration time, meaning the number of seconds to keep resources in the storage backend.
+- Strategy. This means, which is the backing data store in which to hold cache entities. The only accepted values are `memory` and `redis`.
+
+> A complete reference for configuration can be seen [here](https://docs.konghq.com/hub/kong-inc/proxy-cache/).
+
+#### API Consumer
+Clients **SHOULD** be capable of using `max-age` and `max-stale` headers to exclude the entity from being cached entirely or request stale copies of data if necessary.
+
+
+
 ### Common Cache-Control Scenarios
 
 Two, most common scenarios for controlling the cache-ability of a response includes \(1\) Setting expiration and revalidation and \(2\) disabling the caching of a response. Refer to the [Cache-Control Documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) for additional controls.
 
+> Remember the adidas API Gateway identifies the status of the request’s proxy cache behavior via the `X-Cache-Status` header. There are several possible values for this header:
+
+- `Miss` The request could be satisfied in cache, but an entry for the resource was not found in cache, and the request was proxied upstream.
+- `Hit` The request was satisfied and served from cache.
+- `Refresh` The resource was found in cache, but could not satisfy the request, due to Cache-Control behaviors or reaching its hard-coded cache_ttl threshold.
+- `Bypass` The request could not be satisfied from cache based on plugin configuration.
+
 #### 1. Cache Expiration & Revalidation
+Cache revalidation is not yet supported at API Gateway level.
 
 The common scenario to set cache expiration and revalidation policy is to use the `max-age` and `must-revalidate` directives:
 
@@ -24,9 +52,11 @@ Content-Type: application/hal+json; charset=UTF-8
 ...
 ```
 
+That means, `max-age` is the oldest that a response can be, as long as the Cache-Control from the origin server indicates that it is still fresh. 
+
 #### 2. Disabling Cache
 
-To disable caching completely API implementation **SHOULD** use the `no-cache` and `no-store` directives:
+At API Gateway and upstream/backend levels, to disable caching completely API implementation **SHOULD** use the `no-cache` directives:
 
 ```text
 HTTP/1.1 200 OK