Mirrors/api-guidelines
1
0
Fork 0
mirror of https://github.com/adidas/api-guidelines.git synced 2025-10-25 15:19:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Changes in cache section and fixed typos

Browse Source
This commit is contained in:
dediejes
2021-02-16 11:06:20 +01:00
parent d65afa6152
commit 6821cf657a
2 changed files with 31 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
rest-api-guidelines/execution/caching.md
View File

@@ -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.