diff --git a/packages/web/docs/src/pages/docs/gateway/other-features/performance/response-caching.mdx b/packages/web/docs/src/pages/docs/gateway/other-features/performance/response-caching.mdx index f24402d3596..14dd68428d8 100644 --- a/packages/web/docs/src/pages/docs/gateway/other-features/performance/response-caching.mdx +++ b/packages/web/docs/src/pages/docs/gateway/other-features/performance/response-caching.mdx @@ -69,15 +69,27 @@ for the fields and types they are defining. You can add this directive during co ### `@cacheControl` directive -In Apollo Server, `@cacheControl` directive is used to configure the behavior of the response +This directive allows you to control response caching from the subgraph. But its behavior is +different in different gateway and subgraph implementations. In GraphQL Yoga, `@cacheControl` +directive is used to configure the behavior of the response caching plugin, and the response caching +plugin uses `ETag` headers, not `Cache-Control` headers so it can be automatically invalidated by +mutations. Unlike GraphQL Yoga, Apollo Server uses `Cache-Control` directives to set the caching +behavior of the response headers without `ETag` headers and it doesn't validate the cached response +by the client. + +As Apollo Server handles `@cacheControl` directives to configure the behavior of the response headers including `cache-control` of the subgraph server. And in this case, you can just use [HTTP Caching plugin](/docs/gateway/other-features/performance/http-caching) to handle caching headers. If you want to use that approach with Apollo Server, check the relevant docs [here](https://www.apollographql.com/docs/apollo-server/performance/caching). -But in Hive Gateway, it is possible to handle those directives on the gateway level to configure -response caching of the gateway from the subgraph. In this case, you need to expose `@cacheControl` -directive to the supergraph by adding the following definitions; +If you use GraphQL Yoga, you don't have an extra configuration like above unless you want to have +another caching layer on the gateway. + +In order to let the gateway handle the caching behavior rather than the subgraph server, it is +possible to handle those directives on the Hive Gateway level to configure response caching of the +gateway from the subgraph. In this case, you need to expose `@cacheControl` directive to the +supergraph by adding the following definitions; ```graphql extend schema