├── .github
    ├── ISSUE_TEMPLATE.md
    └── PULL_REQUEST_TEMPLATE.md
└── README.md


/.github/ISSUE_TEMPLATE.md:
--------------------------------------------------------------------------------
 1 | 
 2 | <!--**Issue Labels**
 3 | 
 4 | While not necessary, you can help organize our issues by labeling this issue when you open it.  To add a label automatically, simply [x] mark the appropriate box below:
 5 | 
 6 | - [ ] has-reproduction
 7 | - [ ] feature
 8 | - [ ] docs
 9 | - [ ] blocking
10 | - [ ] good first issue
11 | 
12 | To add a label not listed above, simply place `/label another-label-name` on a line by itself.
13 | -->


--------------------------------------------------------------------------------
/.github/PULL_REQUEST_TEMPLATE.md:
--------------------------------------------------------------------------------
 1 | 
 2 | <!--**Pull Request Labels**
 3 | 
 4 | While not necessary, you can help organize our pull requests by labeling this issue when you open it.  To add a label automatically, simply [x] mark the appropriate box below:
 5 | 
 6 | - [ ] feature
 7 | - [ ] blocking
 8 | - [ ] docs
 9 | 
10 | To add a label not listed above, simply place `/label another-label-name` on a line by itself.
11 | -->


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Archival
  2 | This repo was archived by the Apollo Security team on 2023-05-26
  3 | 
  4 | Please reach out at security@apollographql.com with questions.
  5 | 
  6 | 
  7 | ## ⚠️ Deprecation Notice
  8 | 
  9 | This specification is no longer supported by Apollo. Please see our [documentation](https://www.apollographql.com/docs/apollo-server/performance/caching/) for alternative approaches.
 10 | 
 11 | ***
 12 | 
 13 | # Apollo Cache Control Specification
 14 | 
 15 | Apollo Cache Control is a GraphQL extension for fine-grained cache control that can inform server-side or client-side GraphQL caches. It describes a format for a GraphQL API to return information about cache expiration and scope, as well as controls that a client can use to override caching.
 16 | 
 17 | This data can inform [Apollo Studio](https://www.apollographql.com/studio/) or other tools of the cache policies that are in effect for a particular request.
 18 | 
 19 | ## Supported GraphQL Servers
 20 | 
 21 | - [Apollo Server](https://github.com/apollographql/apollo-server)
 22 | 
 23 | > Know of other GraphQL servers which implement this specification? Open a PR to this README to add it to the list!
 24 | 
 25 | ## Response Format
 26 | 
 27 | The GraphQL specification allows servers to [include additional information as part of the response under an `extensions` key](https://facebook.github.io/graphql/#sec-Response-Format):
 28 | > The response map may also contain an entry with key `extensions`. This entry, if set, must have a map as its value. This entry is reserved for implementors to extend the protocol however they see fit, and hence there are no additional restrictions on its contents.
 29 | 
 30 | Apollo Cache Control exposes cache control hints for an individual request under a `cacheControl` key in `extensions`:
 31 | 
 32 | ```
 33 | {
 34 |   "data": ...,
 35 |   "errors": ...,
 36 |   "extensions": {
 37 |     "cacheControl": {
 38 |       "version": 1,
 39 |       "hints: [
 40 |         {
 41 |           "path": [...],
 42 |           "maxAge": <seconds>,
 43 |           "scope": <PUBLIC or PRIVATE>
 44 |         },
 45 |         ...
 46 |       ]
 47 |     }
 48 |   }
 49 | }
 50 | ```
 51 | 
 52 | - The `path` is the response path in a format similar to the error result format specified in the GraphQL specification:
 53 | > This field should be a list of path segments starting at the root of the response and ending with the field associated with the error. Path segments that represent fields should be strings, and path segments that represent list indices should be 0‐indexed integers. If the error happens in an aliased field, the path to the error should use the aliased name, since it represents a path in the response, not in the query.
 54 | 
 55 | - `maxAge` indicates that anything under this path shouldn't be cached for more than the specified number of seconds, unless the value is overridden on a subpath.
 56 | 
 57 | - If `scope` is set to `PRIVATE`, that indicates anything under this path should only be cached per-user, unless the value is overridden on a subpath. `PUBLIC` is the default and means anything under this path can be stored in a shared cache.
 58 | 
 59 | ### Example
 60 | 
 61 | ```graphql
 62 | query {
 63 |   post(id: 1) {
 64 |     title
 65 |     votes
 66 |     readByCurrentUser
 67 |   }
 68 | }
 69 | ```
 70 | 
 71 | ```json
 72 | "cacheControl": {
 73 |   "version": 1,
 74 |   "hints": [
 75 |     {
 76 |       "path": [
 77 |         "post"
 78 |       ],
 79 |       "maxAge": 240
 80 |     },
 81 |     {
 82 |       "path": [
 83 |         "post",
 84 |         "votes"
 85 |       ],
 86 |       "maxAge": 30
 87 |     },
 88 |     {
 89 |       "path": [
 90 |         "post",
 91 |         "readByCurrentUser"
 92 |       ],
 93 |       "scope": "PRIVATE"
 94 |     }
 95 |   ]
 96 | }
 97 | ```
 98 | 
 99 | ## Request Format
100 | 
101 | Apollo Cache Control also allows clients to include cache control instructions in a request. For now, the only specified field is `noCache`, which forces the proxy never to return a cached response, but always fetch the query from the origin.
102 | 
103 | ```json
104 | "extensions": {
105 |   "cacheControl": {
106 |     "version": 1,
107 |     "noCache": true
108 |   }
109 | }
110 | ```
111 | 


--------------------------------------------------------------------------------