graphiti 2.0.0.beta.2 → 2.0.0.beta.4

data/docs/js/writes.md

@@ -0,0 +1,373 @@
+---
+title: 'Writes'
+sidebar_position: 5
+---
+
+Similar to `ActiveRecord`, you can call `#save()` on a model instance. Spraypaint will [create](http://jsonapi.org/format/#crud-creating) (`POST`) or [update](http://jsonapi.org/format/#crud-updating) (`PATCH`) as needed.
+
+`#save()` returns a `Promise` that will resolve a `boolean` - `true` when the server returns a 200-ish response code, `false` when the server returns a `422` response code (see [validations](/js/writes#validations)). As always, anything else will reject the promise.
+
+```typescript
+  let blog = new Blog({ title: "My Blog" })
+  let success = await blog.save() // POST /blogs
+  console.log(success) // true/false
+
+  blog.title = "Updated Title"
+  success = await blog.save() // PUT /blogs/:id
+  console.log(success) // true/false
+```
+
+```javascript
+  var blog = new Blog({ title: "My Blog" });
+  // POST /blogs
+  blog.save().then(function(success) {
+    console.log(success); // true/false
+
+    blog.title = "Updated Title":
+    // PUT /blogs/:id
+    blog.save().then(function(success) {
+      console.log(success) // true/false
+    });
+  });
+```
+
+After saving, the instance will automatically pick up any server-assigned attributes:
+
+```typescript
+  let post = new Post()
+  await post.save()
+  post.id // server-assigned value
+  post.createdAt // server-assigned value
+```
+
+```javascript
+  var post = new Post();
+  post.save().then(function(success) {
+    post.id // server-assigned value
+    post.createdAt // server-assigned value
+  });
+```
+
+If a `Model` was instantiated with data from the server, `isPersisted` will return `true`. This means that we can assign IDs on the client without any adverse behavior. We can also manually mark objects as persisted for testing purposes:
+
+```typescript
+  let blog = new Blog({ id: 123 })
+  blog.isPersisted // false
+  await blog.save() // POST /blogs
+  blog.isPersisted // true
+  blog.id // 123
+
+  // Manually mark an instance as persisted
+  blog = new Blog({ id: 123 })
+  blog.isPersisted = true
+  await blog.save() // PUT /blogs/123
+```
+
+```javascript
+  var blog = new Blog({ id: 123 });
+  blog.isPersisted // false
+  // POST /blogs
+  blog.save().then(function(response) {
+    blog.isPersisted // true
+    blog.id // 123
+  });
+
+  // Manually mark an instance as persisted
+  var blog = new Blog({ id: 123 });
+  blog.isPersisted = true
+  blog.save() // PUT /blogs/123
+```
+
+Notably, **only dirty (changed) attributes will be sent to the server**. This prevents race conditions and unexpected side-effects. In the following example, `Post` has attributes `title`, `description`, and `createdAt`:
+
+```typescript
+  let post = (await Post.first())
+  post.title = "updated"
+  // ONLY title sent to the server
+  await post.save()
+  // Title is now synced with the server
+  post.description = "updated"
+  // ONLY description sent to the server
+  await post.save()
+```
+
+```javascript
+  Post.first().then(function(response) {
+    var post = response.data;
+    post.title = "updated";
+    // ONLY title sent to the server
+    post.save().then(function(response) {
+      // Title is now synced with the server
+      post.description = "updated";
+      // ONLY description sent to the server
+      post.save();
+    });
+  });
+```
+
+## Validations
+
+JSONAPI Suite is already set up to return validation errors with a `422` response code and JSONAPI-compliant [errors payload](http://jsonapi.org/format/#errors). Those errors will be automatically assigned, and removed on subsequent requests:
+
+```typescript
+  let success = await post.save()
+  console.log(success) // false
+  post.errors.title // { message: "Can't be blank", ... }
+  post.title = "no longer blank"
+  success = await post.save()
+  console.log(success) // true
+  post.errors // {}
+```
+
+```javascript
+  post.save().then(function(success) {
+    console.log(success) // false
+    post.errors.title // { message: "Can't be blank", ... }
+    post.title = "no longer blank"
+    post.save().then(function(success) {
+      console.log(success); // true
+      post.errors // {}
+    });
+  })
+```
+
+## Dirty Tracking
+
+When an attribute has been modified, but has not yet been saved to the server, it is considered "dirty". Use `#isDirty()` to see if any attribute is dirty, use the `#changes()` method to see all dirty attributes.
+
+```typescript
+  let post = await Post.first()
+  post.title // "original"
+  post.isDirty() // false
+  post.changes() // {}
+
+  post.title = "changed"
+  post.isDirty() // true
+  post.changes() // { title: ["original", "changed"] }
+
+  await post.save()
+  post.isDirty() // false
+  post.changes() // {}
+```
+
+```javascript
+  Post.first().then(function(response) {
+    var post = response.data;
+
+    post.title; // "original"
+    post.isDirty(); // false
+    post.changes(); // {}
+
+    post.title = "changed";
+    post.isDirty(); // true
+    post.changes(); // { title: ["original", "changed"] }
+
+    post.save().then(function(success) { // true
+      post.isDirty(); // false
+      post.changes(); // {}
+    });
+  });
+```
+
+> Remember, only dirty attributes are sent to the server when `#save()`
+> is called.
+
+`#isDirty()` *can* take into account relationships - just pass a string, array, or object or relationship names. A relationship is considered dirty if:
+
+* Any objects in the relationship have dirty attributes
+* An object was removed from a `hasMany` relationship
+* An object was added to a `hasMany` relationship
+* Any object within the relationship was replaced with a different
+object.
+
+```typescript
+  let post = await Post.first()
+  post.comments[0].text = "my comment"
+  post.isDirty("comments") // true
+
+  post = await Post.first()
+  post.comments.push(new Comment())
+  post.isDirty("comments") // true
+
+  post = await Post.first()
+  post.comments.splice(1, 1)
+  post.isDirty("comments") // true
+
+  post = await Post.first()
+  post.blog // an existing Blog instance
+  post.blog = (await Blog.first()).data
+  post.isDirty("blog") // true
+
+  // check nested relationships
+  post.isDirty(["blog", { comments: "author" }])
+```
+
+```javascript
+  Post.first().then(function(response) {
+    var post = response.data;
+    post.comments[0].text = "my comment";
+    post.isDirty("comments"); // true
+  });
+
+  Post.first().then(function(response) {
+    var post = response.data;
+    post.comments.push(new Comment());
+    post.isDirty("comments"); // true
+  });
+
+  Post.first().then(function(response) {
+    var post = response.data;
+    post.comments.splice(1, 1);
+    post.isDirty("comments"); // true
+  });
+
+  Post.first().then(function(response) {
+    var post = response.data;
+    post.blog; // an existing Blog instance
+
+    Blog.first().then(function(blog) {
+      post.blog = (await Blog.first()).data
+      post.isDirty("blog") // true
+    });
+  });
+
+  // check nested relationships
+  post.isDirty(["blog", { comments: "author" }])
+```
+
+If you need to reset dirty tracking, call `#reset()`
+
+```typescript
+  let post = await Post.first()
+  post.title // "original"
+  post.title = "changed"
+  post.isDirty() // true
+  post.reset()
+  post.title // "changed"
+  post.isDirty() // false
+```
+
+```javascript
+  Post.first().then(function(post) {
+    post.title; // "original"
+    post.title = "changed";
+    post.isDirty() // true
+    post.reset();
+    post.title; // "original"
+    post.isDirty() // false
+  });
+```
+
+## Nested Writes
+
+You can write a `Model` and all of its relationships in a single request. Keep in mind normal dirty tracking rules still apply - nothing is sent to the server unless it is dirty.
+
+```typescript
+  let author = new Author()
+  let comment = new Comment({ author })
+  let post = new Post({ comments: [comment] })
+
+  // post.save({ with: "comments" })
+  // post.save({ with: ["comments", "blog"] })
+  post.save({ with: { comments: 'author' }})
+```
+
+```javascript
+  var author = new Author();
+  var comment = new Comment({ author: author });
+  var post = new Post({ comments: [comment] });
+
+  // post.save({ with: "comments" })
+  // post.save({ with: ["comments", "blog"] })
+  post.save({ with: { comments: "author" }});
+```
+
+Use `model.isMarkedForDestruction = true` to delete the associated object. Use `model.isMarkedForDisassociation = true` to remove the association without deleting the underlying object:
+
+```typescript
+  let post = (await Post.includes("comments").first()).data
+  post.comments[0].isMarkedForDestruction = true
+  post.comments[1].isMarkedForDisassociation = true
+
+  // destroys the first comment
+  // disassociates the second comment
+  await post.save({ with: "comments" })
+```
+
+```javascript
+  Post.includes("comments").first().then(function(response) {
+    var post = response.data;
+    post.comments[0].isMarkedForDestruction = true;
+    post.comments[1].isMarkedForDisassociation = true;
+
+    // destroys the first comment
+    // disassociates the second comment
+    post.save({ with: "comments" })
+  });
+```
+
+You may want to send *only* the `id` of the related object to the server - ensuring the models are associated without updating attributes by accident. Just add `.id` to the relationship name:
+
+```typescript
+  post.save({ with: "comments.id" })
+```
+
+```javascript
+  post.save({ with: "comments.id" })
+```
+
+## Deferred Action
+
+If your update or destroy action takes a long time then the server can respond with status code `202 Accepted` and include background job object in the payload.
+
+Example response:
+```http
+HTTP/1.1 202 Accepted
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "type": "background_jobs",
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "attributes": {
+      "status": "pending"
+    }
+  }
+}
+```
+
+You will need to give the model object a callback called `onDeferredDestroy` or `onDeferredUpdate`. Spraypaint will then call your callback with the deserialized object included in the payload.
+
+```typescript
+let person = new Person({ firstName: 'Jane' })
+person.onDeferredUpdate = (job: any) => {
+  handleBackgroundJob(job);
+}
+person.save()
+
+person.onDeferredDestroy = (job: any) => {
+  handleBackgroundJob(job);
+}
+person.destroy()
+```
+
+```javascript
+const person = new Person({ firstName: 'Jane' });
+person.onDeferredUpdate = (job) => {
+  handleBackgroundJob(job);
+};
+person.save();
+
+person.onDeferredDestroy = (job) => {
+  handleBackgroundJob(job);
+};
+person.destroy();
+```
+
+  <h2 id="next">
+    <a href="/js/middleware">
+      NEXT:
+      <small>Middleware</small>
+      &raquo;
+    </a>
+  </h2>

data/docs/reference/vandal.md

@@ -0,0 +1,63 @@
+---
+title: 'Vandal'
+---
+
+# Vandal
+Vandal is the Graphiti UI. It's helpful for exploring data, testing and
+generating URLs. To take Vandal for a spin, [view our sample app](https://jsonapi-employee-directory.herokuapp.com/vandal) (*initial load may take a second*).
+
+<br />
+<img width="100%" src="/assets/img/legacy/legacy-07aa104495.png" />
+
+
+
+## Installation {#installation}
+
+### Installing via Template {#installing-via-template}
+
+If you ran our [application template](/getting-started/installation),
+you already have Vandal installed. Check your routes to see it mounted.
+
+### Installing via Gem {#installing-via-gem}
+
+* Add the `vandal_ui` gem.
+* Run `rake vandal:install`
+* Mount the engine:
+
+```ruby
+# config/routes.rb
+scope path: ApplicationResource.endpoint_namespace, defaults: { format: :jsonapi } do
+  # ... routes ...
+  mount VandalUi::Engine, at: '/vandal'
+end
+```
+
+That's it! Vandal will dynamically generate a schema at `<api_namespace>/vandal/schema.json`, and you can view the UI at `<api_namespace>/vandal`.
+
+### Manual Installation {#manual-installation}
+
+[Vandal](https://github.com/graphiti-api/vandal) is a VueJS
+application. Grab the [dist files](https://github.com/graphiti-api/vandal/tree/master/dist) and put them anywhere you'd like.
+
+`index.html` has a placeholder, `__SCHEMA_PATH__`. Replace
+this with a URL hosting your schema, and you'll be good to go.
+
+## Usage {#usage}
+
+First, make sure your schema is being correctly generated. You should
+see Vandal make a request something like `/vandal/schema.json` - make
+sure that looks correct. If it doesn't, you may need to bounce your
+server.
+
+After selecting an endpoint, use the left rail to configure your
+request. Click a relationship once to include it in the response.
+If a relationship is included, you can click any row in the table to
+view related data.
+
+Click a relationship twice and you can configure the deep query of
+the associated Resource. In other words, if you're fetching Posts and
+Comments, click `comments` twice to say things like "only active
+comments should be returned".
+
+When you hit 'submit', the top URL bar will change to reflect your query
+and results will show in the center table.

data/docs/reference/why.md

@@ -0,0 +1,13 @@
+---
+title: 'Why REST?'
+---
+
+# Why REST?
+
+Graphiti builds on REST rather than replacing it, which is worth a short explanation if you're weighing it against GraphQL.
+
+The complaints that motivated GraphQL are real. REST APIs often make clients do several round trips and still hand back the wrong shape of data. But those are complaints about how REST APIs are usually built, not about REST. Add eager-loading and a schema to REST and the complaints go away, and you keep the parts of REST that are hard to get back once you've left: addressable URLs, HTTP caching, and Links that let the server change how a relationship resolves without breaking clients.
+
+The other half is conventions. A GraphQL schema is hand-written per type, so filtering and sorting get reinvented on every team. One API spells it `name_contains`, another `name_LIKE`, another exposes no multisort at all. JSON:API already answers those questions, so `?filter[name][prefix]=Ja&sort=-created_at&page[size]=10` means the same thing on every endpoint of every Graphiti API. You define the Resource. The query interface follows from the attribute types.
+
+That's the whole tradeoff: fewer decisions per endpoint, at the cost of a fixed request and response format.

data/docs/topics/authorization.md

@@ -0,0 +1,155 @@
+---
+title: 'Authorization'
+---
+
+Graphiti authorization happens at three independent layers: which records a query can ever see (`base_scope`), which attributes are readable/writable on those records, and which relationships can be sideloaded or sideposted. Each layer is enforced separately, so a guard on one doesn't imply anything about the others.
+
+## Context
+
+Guards need to know who's asking. Every Resource has access to `Graphiti.context` via the `#context` method (`lib/graphiti/resource.rb`). In a Rails app, including `Graphiti::Rails::Context` in your controller wraps every action in `Graphiti.with_context(graphiti_context, action_name.to_sym)`, and `graphiti_context` defaults to the controller instance itself (`lib/graphiti/rails/context.rb`):
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Graphiti::Rails::Context
+end
+```
+
+That means `context` is your controller, and `context.current_user` (or whatever helper method your controller exposes) is available inside any Resource. Outside of Rails, set context manually:
+
+```ruby
+Graphiti.with_context(OpenStruct.new(current_user: user)) do
+  PostResource.all
+end
+```
+
+## Scoping records
+
+Override `#base_scope` to limit which records a Resource can ever return, regardless of filters:
+
+```ruby
+class PostResource < ApplicationResource
+  def base_scope
+    Post.where(account_id: context.current_user.account_id)
+  end
+end
+```
+
+This runs before filtering, sorting, and pagination, so it can't be bypassed by query params. It applies to sideloads too: a `has_many`/`belongs_to`/`has_one` on the related Resource inherits that Resource's `base_scope` unless the relationship itself passes an explicit `base_scope:` option (`lib/graphiti/sideload.rb#base_scope`), so a scoped Resource stays scoped no matter which relationship it's reached through. See [Composing with Scopes](/concepts/resources#composing-with-scopes) for how `base_scope` fits into the rest of query building.
+
+### Knowing which action you're in
+
+`base_scope` runs for every action, and sometimes you want it to behave differently for a collection than for a single record. Use `current_action`, which is the action name as a symbol. Rails sets it from `action_name` when wrapping the request (`lib/graphiti/rails/context.rb#wrap_graphiti_context`):
+
+```ruby
+def base_scope
+  return Post.all if current_action == :show
+  Post.where(account_id: context.current_user.account_id)
+end
+```
+
+Reach for this rather than digging through the query object's internals. `current_action` is public and stable. The params inside `Graphiti::Query` are neither. It is `nil` when nothing set it, which includes a Resource spec that calls `Graphiti.with_context` without a second argument.
+
+## Integrating with Pundit
+
+Graphiti has no built-in Pundit integration, but the two compose cleanly: let Pundit's policy scope decide which records exist, and let Graphiti guards decide which fields and relationships are exposed.
+
+Merge the policy scope in `base_scope`, so it can't be bypassed by query params:
+
+```ruby
+class ApplicationResource < Graphiti::Resource
+  def base_scope
+    Pundit.policy_scope!(context.current_user, model)
+  end
+
+  def current_user
+    context.current_user
+  end
+end
+```
+
+Because `context` is the controller in Rails, per-record authorization stays where it always was: in the action, on the model the proxy hands you:
+
+```ruby
+def show
+  post = PostResource.find(params)
+  authorize post.data
+  respond_with(post)
+end
+```
+
+Note the split: the policy scope answers "which records may appear at all", `authorize` answers "may this user see this specific record", and [attribute guards](#attribute-guards) answer "which fields of it". Reaching for a policy inside an attribute guard works too, since guards can receive the model:
+
+```ruby
+attribute :salary, :integer, readable: :salary_visible?
+
+def salary_visible?(model)
+  Pundit.policy(current_user, model).salary?
+end
+```
+
+## Attribute guards
+
+Pass a symbol, string, or proc to `readable:`/`writable:` on an attribute to gate it per-request. The guard method can optionally accept the model instance and the attribute name as arguments. Arity decides what it receives, and the model is only resolved if a guard actually declares a parameter for it (`lib/graphiti/util/attribute_check.rb`, `lib/graphiti/resource.rb#guard_model`):
+
+```ruby
+class EmployeeResource < ApplicationResource
+  attribute :salary, :integer, writable: :salary_writable?
+
+  def salary_writable?(model_instance, attribute_name)
+    context.current_user.admin? || context.current_user == model_instance.manager
+  end
+end
+```
+
+On create the model is a new unsaved instance. On update it's the persisted record. A failed `writable` guard on a request rejects the write with an `unwritable_attribute` validation error before anything is persisted (`lib/graphiti/request_validators/validator.rb`). A failed `readable` guard omits the attribute from the response (`lib/graphiti/util/serializer_attributes.rb`).
+
+You can set the same guard for every attribute on a Resource with `attributes_readable_by_default`/`attributes_writable_by_default`, which also accept a symbol (`lib/graphiti/resource/configuration.rb`):
+
+```ruby
+class ApplicationResource < Graphiti::Resource
+  self.attributes_writable_by_default = :writable_by_default?
+
+  def writable_by_default?(model_instance, attribute_name)
+    PolicyChecker.new(context.current_user).writable?(model_instance, attribute_name)
+  end
+end
+```
+
+Full option details, including `only`/`except` shorthand, live under [Limiting Behavior](/concepts/resources#limiting-behavior).
+
+## Relationship guards
+
+`has_many`, `belongs_to`, `has_one`, and `many_to_many` accept the same `readable:`/`writable:` guard shape, but unlike attribute guards, relationship guards take no arguments. Base the decision on `context` alone (`lib/graphiti/sideload.rb#evaluate_flag`):
+
+```ruby
+class EmployeeResource < ApplicationResource
+  has_many :salary_histories, readable: :admin?, writable: :admin?
+
+  def admin?
+    context.current_user.admin?
+  end
+end
+```
+
+A failed `readable` guard silently scrubs the relationship from `?include=` before any records are fetched, and omits it from serialized output. A failed `writable` guard rejects a sidepost to that relationship with an `unwritable_relationship` validation error (`lib/graphiti/request_validators/validator.rb`).
+
+The guard method can live on either side of the relationship: Graphiti first looks for it on the resource declaring the relationship, falling back to the related resource if it isn't defined there (`lib/graphiti/sideload.rb#guard_resource`). That lets you define the guard once on the related resource and cover every relationship that points at it.
+
+To audit every guarded relationship across your app (useful before deploying a new guard), call `Graphiti.guarded_relationships`, which returns strings like `"EmployeeResource.salary_histories"` for every relationship whose `readable` or `writable` flag is a symbol, string, or proc (`lib/graphiti.rb#guarded_relationships`).
+
+See [Customizing Relationships](/concepts/relationships#customizing-relationships) for the rest of the relationship option surface.
+
+## Testing authorization
+
+Set context in a spec with `Graphiti.with_context`:
+
+```ruby
+let(:ctx) { OpenStruct.new(current_user: double(admin?: true)) }
+
+it 'exposes salary to admins' do
+  Graphiti.with_context(ctx) { render }
+  expect(d[0].salary).to eq(100_000)
+end
+```
+
+See [Context](/topics/testing#context) in the testing guide for more on setting context in Resource and API specs.

data/docs/topics/caching.md

@@ -0,0 +1,55 @@
+---
+title: 'Caching'
+---
+
+# Caching
+
+Graphiti can cache the rendered JSON response for a request, keyed off the underlying data and the parts of the query that affect rendering. This is opt-in at two levels: a global switch that enables cache-backed rendering, and a per-resource declaration that says which resources actually participate.
+
+## Enabling it
+
+First, tell Graphiti which cache store to use. Any object that responds to `fetch` works, so `Rails.cache` is the usual choice:
+
+```ruby
+Graphiti.cache = Rails.cache
+```
+
+Then turn on cache-backed rendering globally:
+
+```ruby
+Graphiti.configure do |config|
+  config.cache_rendering = true
+end
+```
+
+If `cache_rendering` is `true` but `Graphiti.cache` isn't set to something that responds to `fetch`, Graphiti raises `"You must configure a cache store in order to use cache_rendering. Set Graphiti.cache = Rails.cache, for example."` the first time `Graphiti.config.cache_rendering?` is checked.
+
+`cache_rendering` alone doesn't cache anything, though. Each resource has to opt in with `cache_resource`:
+
+```ruby
+class EmployeeResource < ApplicationResource
+  cache_resource expires_in: 5.minutes, tag: :cache_tag
+end
+```
+
+`expires_in` defaults to `false` (no expiry) and `tag` defaults to `nil`. Calling `cache_resource` sets a resource-level flag that flows through every `all`/`find` call on that resource, so caching applies to both index and show-style requests.
+
+## What actually gets cached
+
+Only the rendered JSON is cached, not the database query. On render, if the resource proxy is cacheable and `Graphiti.config.cache_rendering?` is true, the renderer wraps the render call in `Graphiti.cache.fetch`, keyed by `"graphiti:render/#{proxy.cache_key}"`, versioned by `proxy.updated_at`, and expiring after `proxy.cache_expires_in`. If either condition is false, rendering happens normally with no cache involved.
+
+## Cache key composition
+
+`proxy.cache_key` combines three pieces, joined into a single expanded cache key:
+
+- **Scope cache key**: the underlying object's own `cache_key` (typically an ActiveRecord relation's `cache_key`, so it reflects the resolved records), combined with the `cache_key` of every sideloaded resource proxy. Sideloading `positions` or `department` folds their cache keys into the parent's.
+- **Query cache key**: a SHA1 digest over the parts of the query that affect *rendering*: `extra_fields`, `fields`, whether links are requested, whether pagination links are requested, and `format`. Filters, sorts, and pagination page/size are deliberately not part of this digest. Two requests that select the same rendering options produce the same query cache key even if they filter different data. This is why the key is always combined with the scope key, which does vary with the resolved records.
+- **Resource cache tag**: if `cache_resource` was given a `tag:`, and the resource responds to that method, its value is appended as a third segment (e.g. `cache_resource tag: :cache_tag` calls `resource.cache_tag` and appends the result).
+
+## Versioning and expiry
+
+`proxy.updated_at` is the max `updated_at` across the resolved records (`@object.maximum(:updated_at)`) and every sideloaded proxy's `updated_at`, recursively. If that calculation raises, Graphiti logs the error and falls back to `Time.now`, so a broken `updated_at` calculation degrades to "always fresh" rather than raising into the request. This value is passed as the cache store's `version:` option, so it participates in the effective cache entry the same way `ActiveSupport::Cache::Store#fetch` normally handles versioning. `expires_in` is passed straight through to the cache store as-is from `cache_resource`.
+
+## Debugging cache behavior
+
+When the [debugger](/topics/debugging) is enabled and a request's rendering is actually cached (`proxy.cached?` and `cache_rendering?` both true), the debug output includes a cache section showing the cache key's name, whether it's "stable" or "volatile" (based on how often the key changes across requests), and, when the key does change, which cache-key segments were added or removed. This is built on `Graphiti::Util::CacheDebug`, which persists hit/miss counts in `Graphiti.cache` between requests to compute those stats. See [ETags](/topics/etags) for the related per-response version identifier this same infrastructure computes.