graphiti 2.0.0.beta.7 → 2.0.0.beta.9

data/docs/concepts/links.md

@@ -1,212 +0,0 @@
----
-title: 'Links'
----
-
-# Links
-
-## Overview {#overview}
-
-A [Link](http://jsonapi.org/format/#document-links) is a URL Graphiti puts in a relationship, pointing at the data so a client can fetch it separately. Every relationship gets one automatically:
-
-```ruby
-class PostResource < ApplicationResource
-  has_many :comments
-end
-```
-
-`GET /posts/123` renders the `comments` relationship with a `links.related` of `/comments?filter[post_id]=123`. The client follows that URL when it wants the comments, rather than asking for them up front with `?include=comments`.
-
-### Why links {#why-links}
-
-The URL matters most when the relationship means something more specific than "all the comments". Say `top_comments` is defined as 100 upvotes or more. A [`params` block](#linking-relationships) puts that into the generated Link, and the client still follows a URL.
-
-The alternative is for clients to build that query themselves, which means every client (desktop, mobile, third-party) has to know what a "Top Comment" is and ship an update whenever the definition changes. Hiding it behind a dedicated `/top_comments` endpoint moves the problem rather than solving it: clients still have to know to hit a special endpoint, and nothing keeps its definition in sync with the eager-loaded one.
-
-With a Link, the definition lives in one place. Change it to 500 upvotes, factor in recency, subtract downvotes: clients keep following the same URL.
-
-
-## Linking Relationships {#linking-relationships}
-
-When defining a relationship, we get a Link for free:
-
-```ruby
-class PostResource < ApplicationResource
-  has_many :comments
-end
-```
-
-> `/comments?filter[post_id]=123`
-
-And when customizing a relationship with `params`, our Link will be
-updated:
-
-```ruby
-has_many :comments do
-  params do |hash|
-    hash[:filter][:upvotes] = { gte: 100 }
-  end
-end
-```
-
-> `/comments?filter[post_id]=123&filter[upvotes][gte]=100`
-
-Note: if you use the `scope` block directly, it may cause incorrect links. Avoid using `scope` directly and instead use `params` and `pre_load` if possible.
-
-To manually generate a Link:
-
-```ruby
-has_many :comments do
-  link do |post|
-    helpers = Rails.application.routes.url_helpers
-    helpers.comments_url(params: { filter: { post_id: post.id } })
-    # or
-    # http://example.com/api/v1/comments?filter[post_id]=123
-  end
-end
-```
-
-To avoid a Relationship Link altogether:
-
-```ruby
-has_many :comments, link: false
-```
-
-## Resource Endpoints {#resource-endpoints}
-
-To generate links, we need to associate a Resource to a URL. By default,
-this happens automatically:
-
-```ruby
-class ApplicationResource < Graphiti::Resource
-  # ... code ...
-  self.endpoint_namespace = '/api/v1'
-end
-
-class PostResource < ApplicationResource
-  # under the hood:
-  primary_endpoint 'posts',
-    [:index, :show, :create, :update, :destroy]
-end
-```
-
-Which would generate links to `/api/v1/posts`.
-
-### Validation {#validation}
-
-Associating a Resource to an Endpoint serves two purposes. We've gone
-over link generation. But we also want to make sure we're not linking to
-something that doesn't actually exist. That's why we perform **Endpoint
-Validation**.
-
-If we tried to access the above resource at a `/comments` endpoint:
-
-```ruby
-class CommentsController < ApplicationController
-  def index
-    PostResource.all(params)
-    # ...
-  end
-end
-```
-
-We'd get a `Graphiti::Errors::InvalidEndpoint` error. Endpoint
-validation ensures that our auto-generated Links are actually valid.
-
-To change the endpoint associated to a Resource:
-
-```ruby
-primary_endpoint 'special_posts', [:index, :show]
-```
-
-Or to alter only the **path**:
-
-```ruby
-self.endpoint[:path] = 'special_posts'
-```
-
-Or to alter only the **actions** supported:
-
-```ruby
-self.endpoint[:actions] = [:index, :show]
-```
-
-A resource may be accessible by multiple endpoints. Maybe `PostResource` is also used at `/top_posts`. We want to keep all auto-generated links pointing to `/posts` (the primary endpoint), but *allow* accessing `PostResource` from the `/top_posts` endpoint:
-
-```ruby
-secondary_endpoint '/top_posts', [:index]
-```
-
-## Configuration {#configuration}
-
-### Autolinking {#autolinking}
-
-To turn off automatically generated links:
-
-```ruby
-class ApplicationResource < Graphiti::Resource
-  self.autolink = false
-end
-```
-
-### Endpoint Validation {#endpoint-validation}
-
-To turn off Endpoint Validation:
-
-```ruby
-class ApplicationResource < Graphiti::Resource
-  self.validate_endpoints = false
-end
-```
-
-### Links-on-Demand {#links-on-demand}
-
-To only render links when requested in the URL with `?links=true`:
-
-```ruby
-Graphiti.configure do |c|
-  c.links_on_demand = true
-end
-```
-
-### Pagination Links {#pagination-links}
-
-Requesting large collections can make for slow responses. [Pagination](https://jsonapi.org/format/#fetching-pagination) breaks the response into smaller pieces, and pagination links tell the client how to walk them. They can appear in a response two ways.
-
-#### Showing by default {#pagination-links-showing-by-default}
-
-Every collection response returns pagination links:
-
-```ruby
-Graphiti.configure do |c|
-  c.pagination_links = true
-end
-```
-
-#### When requested {#pagination-links-when-requested}
-
-Links are rendered only when the request asks for them with `?pagination_links=true`. Worth doing when the collection is large: the `last` link needs a total count, so rendering links costs a `stat(:total, :count)` on every request that gets them.
-
-```ruby
-Graphiti.configure do |c|
-  c.pagination_links_on_demand = true
-end
-```
-
-Pagination links won't show up for *#show* actions.
-
-### Custom Endpoint URLs {#custom-endpoint-urls}
-
-To change the URL associated with a Resource:
-
-```ruby
-class PostResource < ApplicationResource
-  # Most commonly seen in ApplicationResource
-  self.endpoint_namespace = '/api/v1'
-
-  primary_endpoint '/posts', [:index, :show]
-  # OR
-  self.endpoint[:path] = '/posts'
-  # OR
-  self.endpoint[:actions] = [:index, :show]
-end
-```

data/docs/concepts/overview.md

@@ -1,80 +0,0 @@
----
-title: 'Lifecycle of a Request'
----
-
-# Lifecycle of a Request
-
-A request goes down through a Resource to your data, and comes back up as a serialized response.
-
-<figure>
-<svg viewBox="0 0 790 300" role="img" aria-label="A request reaches an Endpoint (your Rails controller), then a Resource. The Resource builds a scope from the request, queries your Backend through an Adapter, resolves the results into Models, and serializes them into the JSON:API response that goes back to the client. The Resource and the JSON:API response are Graphiti. The Endpoint and Backend are yours." style={{width: '100%', height: 'auto'}}>
-  <defs>
-    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
-      <path d="M0 0 L10 5 L0 10 z" fill="var(--ifm-color-emphasis-500)"/>
-    </marker>
-    <marker id="arrowStart" viewBox="0 0 10 10" refX="1" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
-      <path d="M10 0 L0 5 L10 10 z" fill="var(--ifm-color-emphasis-500)"/>
-    </marker>
-  </defs>
-
-  <g fill="none" stroke="var(--ifm-color-emphasis-500)" strokeWidth="1.5">
-    <path d="M150 64 H176" markerEnd="url(#arrow)"/>
-    <path d="M310 64 H336" markerEnd="url(#arrow)"/>
-    <path d="M574 96 H626" markerEnd="url(#arrow)" markerStart="url(#arrowStart)"/>
-    <path d="M336 230 H156" markerEnd="url(#arrow)"/>
-    <path d="M85 206 V92" markerEnd="url(#arrow)"/>
-  </g>
-
-  <g stroke="var(--ifm-color-emphasis-300)" fill="var(--ifm-background-surface-color)">
-    <rect x="20" y="40" width="130" height="48" rx="6"/>
-    <rect x="180" y="40" width="130" height="48" rx="6"/>
-    <rect x="630" y="70" width="140" height="52" rx="6"/>
-  </g>
-  <g stroke="var(--ifm-color-primary)" strokeWidth="1.5" fill="none">
-    <rect x="340" y="30" width="230" height="230" rx="8"/>
-    <rect x="20" y="206" width="130" height="48" rx="6"/>
-  </g>
-
-  <g fontFamily="var(--ifm-font-family-base)" fontSize="15" fill="var(--ifm-font-color-base)" textAnchor="middle">
-    <text x="85" y="70">Request</text>
-    <text x="245" y="70">Endpoint</text>
-    <text x="700" y="102">Backend</text>
-    <text x="85" y="236">JSON:API</text>
-  </g>
-  <g fontFamily="var(--ifm-font-family-base)" fontSize="15" fill="var(--ifm-color-primary)" textAnchor="middle">
-    <text x="455" y="62">Resource</text>
-  </g>
-
-  <g fontFamily="var(--ifm-font-family-base)" fontSize="12.5" fill="var(--ifm-color-emphasis-700)" textAnchor="middle">
-    <text x="455" y="104">base_scope + filters,</text>
-    <text x="455" y="122">sorts, pagination</text>
-    <text x="455" y="163">resolve(scope)</text>
-    <text x="455" y="181">to your Models</text>
-    <text x="455" y="222">serialize</text>
-    <text x="600" y="86">Adapter</text>
-  </g>
-  <g fontFamily="var(--ifm-font-family-base)" fontSize="12.5" fill="var(--ifm-color-emphasis-700)">
-    <text x="95" y="152">response</text>
-  </g>
-</svg>
-</figure>
-
-Graphiti is the highlighted part: the Resource, and the JSON:API it renders. The Endpoint is your Rails controller, which handles routing, response codes and MIME types. The Backend is yours too.
-
-| Piece | What it does |
-| --- | --- |
-| [Endpoint](/concepts/endpoints) | Your controller. Graphiti registers its path and actions, which drives link generation and endpoint validation, and lets you vary a Resource's behavior per route. |
-| [Resource](/concepts/resources) | Turns request params into a **scope**, resolves that scope into Models, and serializes them on the way back out. |
-| Adapter | Reusable glue between a Resource and a Backend. Defaults to `Graphiti::Adapters::ActiveRecord`. |
-| [Backend](/concepts/backends-and-models) | Whatever you query: a database, a search index, an HTTP service. |
-| [Model](/concepts/backends-and-models) | What you return and serialize. With ActiveRecord, the same object as the Backend. |
-
-## The graph
-
-Resources connect to other Resources:
-
-* **Sideloading**: fetch an employee, her positions, and those positions' departments in one request
-* **Sideposting**: *save* an employee and her positions in one request
-* **[Links](/concepts/links)**: a URL to lazy-load positions in a separate request
-
-Query logic written for one Resource applies at every level of that graph, so you can ask for an employee and her last three positions ordered by `created_at`. That's [deep querying](/concepts/relationships#deep-queries).

data/docs/concepts/persisting.md

@@ -1,376 +0,0 @@
----
-title: 'Persisting'
----
-
-# Persisting {#persisting}
-
-This page covers how Graphiti writes data: the persistence lifecycle, sideposting a graph of resources in one request, validation errors, and reading data back after a write.
-
-Graphiti allows writing a graph of data in a single request. We'll do
-the work of parsing the graph and ordering operations, so you can focus
-on the part you care about: the logic for actually persisting an object.
-
-By default, persistence operations are handled by your adapter, and the flow breaks into three steps: build or find the model, assign attributes to it, then save it.
-
-Attributes are assigned up front, before the persistence hooks run. That means the model exists (populated but unwritten) before anything touches the database, and **the model you inspect is the model that saves**:
-
-```ruby
-employee = EmployeeResource.build(payload)
-
-employee.data           # the model, attributes already assigned, nothing written yet
-employee.data.valid?    # inspect it, or modify it
-employee.save           # persists that same instance
-```
-
-Reading `data` repeatedly returns the same instance, and the attribute callbacks run only once no matter how often you read it. For an update, the proxy reads the persisted record until you apply the payload:
-
-```ruby
-proxy = EmployeeResource.find(payload)
-proxy.data.first_name       # => "asdf", straight from the database
-proxy.assign_attributes(payload)
-proxy.data.first_name       # => "Jane", assigned but not yet persisted
-proxy.save(action: :update)
-```
-
-`assign_attributes` validates the payload and runs your writable guards, but writes nothing. `#save` will not re-validate a payload it already validated, so inspecting the model costs no extra guard evaluations. `ResourceProxy#update` is the Rails-style shorthand that assigns and saves in one call.
-
-You can override `#create`, `#update` and `#destroy` on a Resource, but you are encouraged **not** to. Use the hooks below instead. If you do override them, `#create` and `#update` receive an attributes hash while `#destroy` receives an id, and all three **must return the Model instance**. Graphiti processes any `writable: false` or guarded attributes before these methods run, and checks the returned Model for validation errors afterward, rolling back the transaction if any Model in the graph is invalid.
-
-## Persistence Lifecycle Hooks {#persistence-lifecycle-hooks}
-
-Let's dive into a persistence request. If you look at the code snippets in
-the prior section, the flow breaks down into 3 steps:
-
-* Build or find the model
-* Assign attributes to the model
-* Save
-
-You can hook into each step:
-
-```ruby
-class PostResource < ApplicationResource
-  before_attributes do |attributes|
-    # Before attributes have been assigned to the model
-  end
-
-  after_attributes do |model|
-    # After attributes have been assigned to the model
-  end
-
-  around_attributes :do_around_attributes
-
-  def do_around_attributes(attributes)
-    # before
-    model_instance = yield attributes
-    # after
-  end
-
-  before_save do |model|
-    # After attributes assigned, but before persisting
-  end
-
-  after_save do |model|
-    # After model has been saved
-  end
-
-  around_save :do_around_save
-
-  def do_around_save(model)
-    # before
-    yield model
-    # after
-  end
-
-  # This is an *override*
-  # During #create, build a blank model instance
-  # By default, we'd call adapter.build(model_class)
-  def build(model_class)
-    model_class.new
-  end
-
-  # This is an *override*
-  # During #create/#update, assign new attributes to the model instance
-  # By default, we'd call adapter.assign_attributes(model_instance, attributes)
-  def assign_attributes(model_instance, attributes)
-    attributes.each_pair do |key, value|
-      model_instance.send(:"#{key}=", value)
-    end
-  end
-
-  # This is an *override*
-  # During #create/#update, actually save the model instance
-  # By default, we'd call adapter.save(model_instance)
-  def save(model_instance)
-    model_instance.save
-    model_instance
-  end
-
-
-  # This is an *override*
-  # During #destroy, actually save the model instance
-  # By default, we'd call adapter.destroy(model_instance)
-  def delete(model_instance)
-    model_instance.destroy
-    model_instance
-  end
-
-  # Finally, you may want to hook around *all* the above steps:
-  # Only applies to #create/#update
-  around_persistence :do_around_persistence
-
-  def do_around_persistence(attributes)
-    attributes[:foo] = 'bar'
-    model = yield # build/find, assign attrs, save
-    model.update_counter_cache
-  end
-end
-```
-
-* All hooks have `only/except` options, e.g. `before_attributes only: [:update]`
-* Most hooks can be called with an in-line block, or by passing a method
-name (e.g. `before_attributes :do_something`). The exception is `around_*` hooks, which *must* be called with a method name.
-
-When persisting multiple objects at once, we'll open a database
-transaction, process each model individually, ensure all models pass
-validation, then close the transaction. This means that if you raise an
-error at any point, or any model does not pass validations, the
-transaction will be rolled back.
-
-You may want to perform an operation after all models have been
-processed and validated, but before the transaction is closed. One
-example is sending an email - you don't want to send if the models were
-invalid, so `after_save` wouldn't work. And you still want to do it
-*within* the transaction, so if your email server is down and an error
-is raised the transaction gets rolled back.
-
-For this scenario, use `before_commit`:
-
-```ruby
-before_commit do |model|
-  PostMailer.with(post: model).some_email.deliver
-end
-```
-
-## Sideposting {#sideposting}
-
-The act of persisting multiple Resources in a single request is called
-**Sideposting**. The payload mirrors the **sideloading** payload for
-read operations, with minor additions.
-
-Let's create a Post and associate it to an existing Blog in a single
-request:
-
-```ruby
-# POST /api/v1/posts
-{
-  type: 'posts',
-  attributes: { title: 'My post' },
-  relationships: {
-    blog: {
-      data: {
-        id: '1',
-        type: 'blogs',
-        method: 'update'
-      }
-    }
-  }
-}
-```
-
-The critical addition here is the `method` key. When we persist RESTful
-Resources, we send a corresponding HTTP verb. This follows the same
-pattern, adding a verb for each Resource in the graph. `method` can be
-one of:
-
-  * `create`
-  * `update`
-  * `destroy`
-  * `disassociate` (e.g. `null` foreign key)
-
-When we sidepost, all objects will be persisted within the same database
-transaction, which rolls back if an error is raised or any objects are invalid.
-
-### Create {#create}
-
-Let's say we want to create a Post and its Blog in a single request.
-You'll note that we don't have the `id` key to generate a [Resource Identifier](http://jsonapi.org/format/#document-resource-identifier-objects) (combination of `id` and `type`
-that uniquely identifies a Resource).
-
-To accomodate this, send an ephemeral `temp-id` (any UUID):
-
-```ruby
-{
-  # POST /api/v1/posts
-  {
-    type: 'posts',
-    attributes: { title: 'My post' },
-    relationships: {
-      blog: {
-        data: {
-          :'temp-id' => 'abc123',
-          type: 'blogs',
-          method: 'create'
-        }
-      }
-    },
-    included: [
-      {
-        :'temp-id' => 'abc123'
-        type: 'blogs',
-        attributes: { name: 'New Blog' }
-      }
-    ]
-  }
-}
-```
-
-This random UUID:
-
-* Connects relevant sections of the payload.
-* Tells clients how to associate their in-memory objects with the ids returned from the server.
-
-### Expanded Example {#expanded-example}
-
-Here we're updating a Post, changing the name of its associated Blog, creating a Tag, deleting one Comment, and disassociating (`null` foreign key) a different Comment, all in a single request:
-
-```ruby
-{
-  data: {
-    type: 'posts',
-    id: 123,
-    attributes: { title: 'Updated!' },
-    relationships: {
-      blog: {
-        data: {
-          type: 'blogs',
-          id: 123,
-          method: 'update'
-        }
-      },
-      tags: {
-        data: [{
-          type: 'tags',
-          temp-id: 's0m3uu1d',
-          method: 'create'
-        }]
-      },
-      comments: {
-        data: [
-          {
-            type: 'comments',
-            id: '123',
-            method: 'destroy'
-          },
-          {
-            type: 'comments',
-            id: '456',
-            method: 'disassociate'
-          }
-        ]
-      }
-    }
-  },
-  included: [
-    {
-      type: 'tags',
-      :'temp-id' => 's0m3uu1d',
-      attributes: { name: 'Important' }
-    },
-    {
-      type: 'blogs',
-      id: => '123',
-      attributes: { name: 'Updated!' }
-    }
-  ]
-}
-```
-
-## Validation Errors {#validation-errors}
-
-When a persistence operation is attempted but the corresponding Resource
-is invalid, the transaction will be rolled back and an [errors payload](http://jsonapi.org/format/#errors) will be returned
-with a `422` response code:
-
-```ruby
-{
-  errors: [{
-    code:  'unprocessable_entity',
-    status: '422',
-    title: "Validation Error",
-    detail: "Title can't be blank",
-    source: { pointer: '/data/attributes/title' },
-    meta: {
-      attribute: :title,
-      message: "can't be blank",
-      code: :blank
-    }
-  }]
-}
-```
-
-To get this functionality, your Model must adhere to the
-[ActiveModel::Validations API](https://api.rubyonrails.org/classes/ActiveModel/Validations.html).
-
-You get this for free with ActiveRecord, or it can be mixed in to any
-PORO:
-
-```ruby
-class Post
-  include ActiveModel::Validations
-  validates :title, presence: true
-end
-```
-
-Errors on associations will have a slightly expanded payload:
-
-```ruby
-{
-  errors: [{
-    code: 'unprocessable_entity',
-    status: '422',
-    title: 'Validation Error',
-    detail: "Name can't be blank",
-    source: { pointer: '/data/attributes/name' },
-    meta: {
-      relationship: {
-        attribute: :name,
-        message: "can't be blank",
-        code: :blank,
-        name: :pets,
-        id: '444',
-        type: 'pets'
-      }
-    }
-  }]
-}
-```
-
-When [Sideposting](#sideposting), the errors payload will contain all
-invalid Resources in the graph.
-
-## Read on Write {#read-on-write}
-
-By default, the response of a persistence operation will mirror your
-request. But sometimes you need control over the response. The most
-common scenario is sideloading an additional entity - imagine creating
-an order, and wanting the order's shipping information to come back in
-the response.
-
-You can do this by POSTing the payload as normal, but adding query
-parameters to the URL:
-
-```ruby
-# POST /api/v1/orders?include=shipping_information
-
-{
-  type: 'orders',
-  attributes: { ... }
-}
-```
-
-This will sideload the shipping information in the response. When using
-[Spraypaint](/js/), do this with:
-
-```typescript
-order.save({ returnScope: Order.includes('shipping_information') })
-```