From 6821cf657a576bfb87d0527fc3593979914d7f4f Mon Sep 17 00:00:00 2001 From: dediejes Date: Tue, 16 Feb 2021 11:06:20 +0100 Subject: [PATCH] Changes in cache section and fixed typos --- rest-api-guidelines/execution/caching.md | 55 ++++++++++--------- .../execution/long-running-tasks/README.md | 2 +- 2 files changed, 31 insertions(+), 26 deletions(-) diff --git a/rest-api-guidelines/execution/caching.md b/rest-api-guidelines/execution/caching.md index 6331dee..32358d2 100644 --- a/rest-api-guidelines/execution/caching.md +++ b/rest-api-guidelines/execution/caching.md @@ -1,8 +1,9 @@ # Caching -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)\). +> From an architectural point of view, the API cache strategy can be defined at two main levels: backend service and API Gateway. These guidelines handle the cache strategy in the backend service as part of the API implementation. Please consider additional cache settings to be defined in the **API Gateway** can dramatically improve the performance and API consumer experience but they have to be defined in a specific way in the adidas product. + +As a general guideline, 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)\). -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 @@ -28,46 +29,50 @@ Clients **SHOULD** be capable of using `max-age` and `max-stale` headers to excl ### 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. +Most common scenarios for controlling the cache-ability of a response includes: + +1. Setting expiration and revalidation. +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 information. > 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. +> - `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. +You **SHOULD** define the expiration time and the case for revalidation in your API. -The common scenario to set cache expiration and revalidation policy is to use the `max-age` and `must-revalidate` directives: +`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. The value means seconds. + +From the semantic point of view `no-cache` and `max-age=0`, `must-revalidate` indicates same meaning: The backend service has to be contacted to get a stale result. + +Clients can cache a resource but must revalidate each time before using it. This means HTTP request occurs each time though, it can skip downloading HTTP body if the content is valid. + +The common scenario to set cache expiration and revalidation policy is to use the `max-age`, `must-revalidate` or `max-age` as part of the `Cache-Control` directives. + +The TTL is set to 5 minutes: ```text -HTTP/1.1 200 OK -Date: Mon, 19 Aug 2017 00:00:00 CEST -Last-Modified: Mon, 19 Aug 2017 00:00:00 CEST -Cache-Control: max-age=3600,must-revalidate -Content-Type: application/hal+json; charset=UTF-8 - -... +Cache-Control: max-age=300 ``` -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. +The cached response has to be refreshed: + +```text +Cache-Control: must-revalidate +``` #### 2. Disabling Cache -At API Gateway and upstream/backend levels, to disable caching completely API implementation **SHOULD** use the `no-cache` directives: +To disable caching completely the API consumer implementation **SHOULD** use the `no-cache` directive: ```text -HTTP/1.1 200 OK -Date: Mon, 19 Aug 2017 00:00:00 CEST -Last-Modified: Mon, 19 Aug 2017 00:00:00 CEST -Cache-Control: no-cache, no-store, must-revalidate -Content-Type: application/hal+json; charset=UTF-8 - -... +Cache-Control: no-cache ``` + ## ETag Every API implementation's response to a [cacheable request](https://github.com/for-GET/know-your-http-well/blob/master/methods.md#cacheable) **SHOULD** include the [`ETag` HTTP Header](https://tools.ietf.org/html/rfc7232#section-2.3) to identify the specific version of the returned resource. diff --git a/rest-api-guidelines/execution/long-running-tasks/README.md b/rest-api-guidelines/execution/long-running-tasks/README.md index d167f37..b94cee8 100644 --- a/rest-api-guidelines/execution/long-running-tasks/README.md +++ b/rest-api-guidelines/execution/long-running-tasks/README.md @@ -1,6 +1,6 @@ # Long Running Tasks -This section includes the recommended approaches to handling long runnint tasks (LRTs) in REST APIs. +This section includes the recommended approaches to handling long running tasks (LRTs) in REST APIs. You can identify a LRT quite easily. The main factor to consider are the metrics from latency of the endpoint. If it requiress tens of seconds even minutes we are facing a problem related to LRTs.