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

data/docs/concepts/endpoints.md

@@ -0,0 +1,183 @@
+---
+title: 'Endpoints'
+---
+
+## Overview {#overview}
+
+**Endpoints** expose and customize
+[Resources](/concepts/resources).
+
+Resources themselves can operate completely independently of a request or response:
+
+```ruby
+employees = EmployeeResource.all({
+  filter: { title: 'engineer' },
+  sort: '-created_at',
+  page: { size: 10 },
+  include: 'positions.department'
+})
+
+employees.map(&:first_name) # => ['Jane', 'John', ...]
+employees.to_json # => { employees: [{ ... }] }
+```
+
+And Resources connect to other Resources. Our graph of data is defined
+**outside** of the actual API.
+
+Endpoints expose this graph to the world. We might choose to have a `/employees` endpoint that can eager load comments (`?include=comments`), but never expose `/comments` directly. Or, we could do the opposite: expose lazy-loading `/comments`, but disallow eager loading from `/employees`. We can add caching rules, or add an `/exemplary_employees` endpoint with special query overrides.
+
+Finally, Endpoints are in charge of the [HTTP specification](https://tools.ietf.org/html/rfc2616):
+request processing, response codes, caching, MIME types, and so on. If you're thinking
+Rails, an Endpoint is the combination of a Route and Controller.
+
+### Endpoint Logic {#endpoint-logic}
+
+Often, you won't need to customize Endpoints - especially if you're
+using our [Rails Resource
+generator](/concepts/resources#generators). Endpoint logic mostly
+concerns:
+
+* Caching
+* Side-effect behavior specific to the endpoint (e.g.: sending a
+welcome email from `/users#create` but not `/admin/users#create`)
+* Authorization (e.g `before_action`)
+* Custom query parameter handling
+* Validation handling
+* Error handling
+* Limiting Resource behavior
+* Customizing Resource behavior
+
+If your logic falls elsewhere, consider a Resource or Model.
+
+### Rails Integration {#rails-integration}
+
+When using Rails, an endpoint is the combination of a Route and
+Controller:
+
+```ruby
+# config/routes.rb
+resources :posts, only: [:index]
+
+# app/controllers/posts_controller.rb
+class PostsController < ApplicationController
+  def index
+    posts = PostResource.all(params)
+    respond_with(posts)
+  end
+end
+```
+
+You'll note that Graphiti hooks into Rails with a mixin (set when using
+our application generator):
+
+```ruby
+class ApplicationController < ActionController::API
+  include Graphiti::Rails::Controller
+
+  # ... code ...
+end
+```
+
+This gives us [#sideload_allowlist](#sideload-allowlist) and sets the
+[context](/concepts/resources#context).
+
+## Customizing Resources {#customizing-resources}
+
+### Scope Overrides {#scope-overrides}
+
+One common use case for endpoints is customizing the Resource
+[base scope](/concepts/resources#base-scope). This causes a new
+"starting point" for query building.
+
+Consider the endpoints `/posts` (basic CRUD) and `/top_posts`. Though both are associated to PostResource, `/top_posts` ensures that only
+Posts with a certain number of upvotes get returned:
+
+```ruby
+def index
+  base_scope = Post.where("upvotes > ?", 100)
+  posts = PostResource.all(params, base_scope)
+  respond_with(posts)
+end
+```
+
+We're able to reuse all the other logic in PostResource - relationships,
+filters, sorts, etc - while only returning "Top Posts".
+
+### Sideload Allowlist {#sideload-allowlist}
+
+Resources define relationships to other resources. But we may not want
+all of those relationships exposed at a given endpoint.
+
+Let's say we've defined relationships:
+
+`Employee > Position > Department > Hardware > CostHistory`
+
+It's reasonable to get an Employee, their Positions, and Departments for
+those positions in a single request. But is it really valid to *also* pull down
+all the hardware, as well as all the historical data on the cost of that hardware,
+in a single request? Allowing the entire graph to be pulled down in a single request can cause excessive load on our
+servers (and this is probably a better fit for lazy-loading via
+[Links](/concepts/links)).
+
+Let's instead say that if we're entering the graph at `/employees`, the
+furthest we can go is Department:
+
+```ruby
+class EmployeesController < ApplicationController
+  self.sideload_allowlist = {
+    index: { positions: 'department' }
+  }
+
+  # ... code ...
+end
+```
+
+## Caching {#caching}
+
+### Etags {#etags}
+
+[ETags](https://robots.thoughtbot.com/introduction-to-conditional-http-caching-with-rails) are an important concept that is often overlooked. Etags tell browsers
+that the response to a GET request hasn't changed since the last request and
+can be safely pulled from the browser cache. If you care about sparse fieldsets,
+you should care about ETags - if you're limiting fields to reduce payload size,
+how about a payload size of **zero**?
+
+ETags are set by default in Rails, by checking the response body. This won't prevent queries from executing, but it will save clients from downloading the response again if nothing has changed.
+
+Let's manually set an ETag:
+
+```ruby
+def index
+  posts = PostResource.all(params)
+
+  if stale?(posts.data)
+    respond_with(posts)
+  end
+end
+```
+
+From the [documentation on #stale?](https://api.rubyonrails.org/classes/ActionController/ConditionalGet.html#method-i-stale-3F):
+
+> *In this case last_modified will be set by calling `maximum(:updated_at)` on the collection (the timestamp of the most recently updated record) and the etag by passing the object itself.*
+
+Also consider the use case where data is ingested hourly. We can avoid a
+query altogether by checking when the last ingestion ran:
+
+```ruby
+def index
+  if stale?(EmployeeIngestion.last)
+    employees = EmployeeResource.all(params)
+    respond_with(employees)
+  end
+end
+```
+
+> **CAVEAT**: When setting ETags, consider sideloads. In the above examples
+> we are checking to see the last update of an Employee, but we may be
+> sideloading (and filtering) Positions as well. Use custom endpoints or
+> [Sideload Allowlist](#sideload-allowlist) to mitigate this issue.
+
+## Testing  {#testing}
+
+If you have custom Endpoint logic, we suggest testing using an [API
+Test](/topics/testing#api-tests).

data/docs/concepts/links.md

@@ -0,0 +1,212 @@
+---
+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 big collections can result into slow responses sometimes. In order to avoid this, you could use [pagination](https://jsonapi.org/format/#fetching-pagination). It'll break your response into smaller pieces that will make your server responds faster. Paginations links can be present in your response in the following ways:
+
+#### Showing by default {#pagination-links-showing-by-default}
+
+With this configuration, all the responses will return the pagination links
+
+```ruby
+Graphiti.configure do |c|
+  c.pagination_links = true
+end
+```
+
+#### When requested {#pagination-links-when-requested}
+
+You can showing the pagination links when it was requested in the URL with `?pagination_links=true`
+
+```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

@@ -0,0 +1,80 @@
+---
+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).