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

data/docs/tutorial/step_6.md

@@ -0,0 +1,82 @@
+---
+title: 'Step 6'
+---
+
+### Step 6: Customizing Writes
+
+> [View the Diff](https://github.com/graphiti-api/employee_directory/compare/step_5_has_one...step_6_write_customization)
+
+When we ran the generators (and created a blank Resource class), we got the ability to create, update, and destroy resources for free. You can turn off this behavior with `self.read_only = true`. Or for relationships: `has_many :positions, writable: false`.
+
+But in RESTful APIs, it's super common for persistence operations to
+have side effects - that's how we avoid extraneous verbs and
+inconsistent patterns.
+
+In a prior step, we updated `position` Factory to automatically reorder the `historical_index`: when a new record comes in, all the prior
+values need to change. This step will show how to add that behavior to
+our API, using hooks that work for a variety of scenarios: sending
+emails, checking authorization roles, queuing delayed jobs, and more.
+
+### The Rails Stuff 🚂
+
+Previously, we put the logic that re-ordered the `historical_index` column in the `position` factory. Let's move that to the model so our
+tests and API can share the same logic:
+
+```ruby
+# app/models/position.rb
+def self.reorder!(employee_id)
+  scope = Position.where(employee_id: employee_id).order(created_at: :desc)
+  scope.each_with_index do |p, index|
+    p.update_attribute(:historical_index, index + 1)
+  end
+end
+```
+
+```ruby
+# spec/factories/positions.rb
+# ... code ...
+after(:create) do |position|
+  unless position.historical_index
+    Position.reorder!(position.employee.id)
+  end
+end
+```
+
+### The Graphiti Stuff 🎨
+
+All Graphiti updates happen within a transaction. We want to insert our
+code right before that transaction closes - after the graph of objects
+has been persisted and validations have passed. To do that, we'll use
+the `before_commit` hook:
+
+```ruby
+before_commit only: [:create, :destroy] do |position|
+  Position.reorder!(position.employee_id)
+end
+```
+
+Again, the `Position.reorder!` code existed independent of our
+API, and was re-used in our factory.
+
+#### Digging Deeper 🧐
+
+Resources come with [Lifecycle Hooks](https://www.graphiti.dev/guides/concepts/persisting#persistence-lifecycle-hooks), similar to ActiveRecord [Callbacks](https://guides.rubyonrails.org/active_record_callbacks.html).
+
+Those callbacks have gotten a bad reputation. This is because your Model
+can be - is supposed to be - used in a variety of contexts across your
+application. Some of those contexts will want a given callback to fire,
+others will not, and accomodating the conditionals gets hairy. This is
+why many developers move that functionality into [Service Objects](https://engineering.gusto.com/the-rails-callbacks-best-practices-used-at-gusto/).
+
+But Resource callbacks don't have the same problem - they only fire in
+the context of your API, and can be associated to a single endpoint. You
+can still use Service Objects if you'd like. Graphiti callbacks wire them up.
+
+
+  <h2 id="next">
+    <a href="/tutorial/step_7">
+      NEXT - 
+      <small>Step 7: Many to Many</small>
+      &raquo;
+    </a>
+  </h2>

data/docs/tutorial/step_7.md

@@ -0,0 +1,205 @@
+---
+title: 'Step 7'
+---
+
+### Step 7: Many to Many
+
+> [View the Diff](https://github.com/graphiti-api/employee_directory/compare/step_6_write_customization...step_7_many_to_many)
+
+Let's add a `Team` relationship: a `Team` can have many `Employee`s, an `Employee` can have many `Team`s. Let's also say a `Team` belongs to a `Department`.
+
+<table class="table table-small text-center">
+  <thead>
+    <tr>
+      <th class="text-center">id</th>
+      <th class="text-center">department_id</th>
+      <th class="text-center">name</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td>1</td>
+      <td>The A Team</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td>1</td>
+      <td>The B Team</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td>2</td>
+      <td>The C Team</td>
+    </tr>
+  </tbody>
+</table>
+
+To satisfy this many-to-many use case, we'll need a join model,
+`TeamMembership`:
+
+<table class="table table-small text-center">
+  <thead>
+    <tr>
+      <th class="text-center">id</th>
+      <th class="text-center">team_id</th>
+      <th class="text-center">employee_id</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td>1</td>
+      <td>1</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td>2</td>
+      <td>1</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td>3</td>
+      <td>2</td>
+    </tr>
+  </tbody>
+</table>
+
+### The Rails Stuff 🚂
+
+```bash
+$ bin/rails g model Team name:string department:belongs_to
+$ bin/rails g model TeamMembership employee:belongs_to team:belongs_to
+$ bin/rails db:migrate
+```
+
+Graphiti supports `has_many :through`:
+
+```ruby
+# app/models/employee.rb
+has_many :team_memberships
+has_many :teams, through: :team_memberships
+```
+
+```ruby
+# app/models/department.rb
+has_many :teams
+```
+
+```ruby
+class Team < ApplicationRecord
+  belongs_to :department
+  has_many :team_memberships
+  has_many :employees, through: :team_memberships
+end
+```
+
+```ruby
+class TeamMembership < ApplicationRecord
+  belongs_to :team
+  belongs_to :employee
+end
+```
+
+Finally, we'll need a new seed file to handle these new associations:
+
+```ruby
+[
+  Employee,
+  Position,
+  Department,
+  TeamMembership,
+  Team
+].each(&:delete_all)
+
+departments = []
+def create_department(name)
+  dept = Department.create! name: name
+  dept.teams.create!(name: 'Engineering Team B')
+  dept.teams.create!(name: 'Engineering Team C')
+  dept
+end
+
+departments << create_department('Engineering')
+departments << create_department('Safety')
+departments << create_department('QA')
+
+100.times do
+  employee = Employee.create! first_name: Faker::Name.first_name,
+    last_name: Faker::Name.last_name,
+    age: rand(20..80)
+
+  (1..2).each do |i|
+    employee.positions.create! title: Faker::Job.title,
+      historical_index: i,
+      active: i == 1,
+      department: departments.sample
+  end
+
+  employee.teams << employee.positions[0].department.teams.sample
+end
+```
+
+### The Graphiti Stuff 🎨
+
+```bash
+$ bin/rails g graphiti:resource Team name:string
+```
+
+Let's flesh out our `TeamResource`:
+
+```ruby
+# app/resources/team_resource.rb
+class TeamResource < ApplicationResource
+  attribute :department_id, :integer, only: [:filterable]
+  attribute :name, :string
+
+  belongs_to :department
+  many_to_many :employees
+end
+```
+
+The trick here is the `many_to_many` relationship. Let's add the reverse
+as well:
+
+```ruby
+# app/resources/employee_resource.rb
+many_to_many :teams
+```
+
+And for good measure:
+
+```ruby
+# app/resources/department_resource.rb
+has_many :teams
+```
+
+We can now get all the usual functionality: fetch Employees and their
+Teams in a single request (or vice versa).
+
+#### Digging Deeper 🧐
+
+The `many_to_many` relationship is the only one where Graphiti modifies a separate Resource "under the hood". When we said `many_to_many
+:employees`, the `EmployeeResource` got a `team_id` filter, and `many_to_many :teams` created an `employee_id` filter on `TeamResource`.
+
+This is because the logic is more complex than the default use case. We
+don't have a simple `WHERE` clause. We need to join tables and look at
+the appropriate primary/foreign keys. If the name of your API
+association doesn't match the name of your ActiveRecord association, try
+`has_many :things, as: :my_activerecord_relationship` to make the
+introspection work correctly - or, write your own filter.
+
+Sometimes you'll have multiple levels of `has_many :through`. In this case, a simple `many_to_many` isn't enough - check out the [Hopping
+Relationships](/topics/hopping-relationships) recipe.
+
+Think hard before reaching for `many_to_many`. Imagine one Team is the "primary" Team for an Employee. We'd add a `primary` boolean column to the `team_memberships` table...but that table isn't exposed to the API!
+Consider if there's a hidden domain concept there.
+
+
+  <h2 id="next">
+    <a href="/tutorial/step_8">
+      NEXT - 
+      <small>Step 8: Polymorphic Relationships</small>
+      &raquo;
+    </a>
+  </h2>

data/docs/tutorial/step_8.md

@@ -0,0 +1,128 @@
+---
+title: 'Step 8'
+---
+
+### Step 8: Polymorphic Relationships
+
+> [View the Diff](https://github.com/graphiti-api/employee_directory/compare/step_7_many_to_many...step_8_polymorphic_belongs_to)
+
+Let's introduce the concept of a Note. A Note can belong to a
+Department, an Employee, or a Team. For this, we'll need to introduce
+the concept of [polymorphism](https://guides.rubyonrails.org/association_basics.html#polymorphic-associations).
+
+<table class="table table-small text-center">
+  <thead>
+    <tr>
+      <th class="text-center">id</th>
+      <th class="text-center">notable_id</th>
+      <th class="text-center">notable_type</th>
+      <th class="text-center">body</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td>1</td>
+      <td>Employee</td>
+      <td>A Sample Note!</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td>1</td>
+      <td>Department</td>
+      <td>Another Sample Note!</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td>1</td>
+      <td>Team</td>
+      <td>A Third Sample Note!</td>
+    </tr>
+  </tbody>
+</table>
+
+### The Rails Stuff 🚂
+
+```bash
+$ rails generate model Note notable:references{polymorphic}:index
+$ bin/rails db:migrate
+```
+
+Make sure to add the corresponding model relationships:
+
+```ruby
+# app/models/employee.rb
+has_many :notes, as: :notable
+# app/models/team.rb
+has_many :notes, as: :notable
+# app/models/department.rb
+has_many :notes, as: :notable
+
+# app/models/note.rb
+belongs_to :notable, polymorphic: true
+```
+
+Finally, make sure to edit your seed file - check out the [diff](https://github.com/graphiti-api/employee_directory/compare/step_7_many_to_many...step_8_polymorphic_belongs_to) to see the necessary adjustments.
+
+### The Graphiti Stuff 🎨
+
+```bash
+$ bin/rails g graphiti:resource Note body:string
+```
+
+Let's create our `NoteResource`:
+
+```ruby
+class NoteResource < ApplicationResource
+  attribute :body, :string
+
+  filter :notable_id, :integer
+  filter :notable_type, :string, allow: %w(Employee Department Team)
+
+  polymorphic_belongs_to :notable do
+    group_by(:notable_type) do
+      on(:Employee)
+      on(:Team)
+      on(:Department)
+    end
+  end
+end
+```
+
+And corresponding associations:
+
+```ruby
+# app/resources/employee_resource.rb
+polymorphic_has_many :notes, as: :notable
+# app/resources/team_resource.rb
+polymorphic_has_many :notes, as: :notable
+# app/resources/department_resource.rb
+polymorphic_has_many :notes, as: :notable
+```
+
+#### Digging Deeper 🧐
+
+When defining a polymorphic relationship for our API, we're saying "grab
+all the parent records, group them by a `type` column, and execute different queries for each type". This way records with `notable_type ==
+'Employee'` can hit the `employees` table, but records with `notable_type == 'Department'` could in theory load from a different API
+altogether.
+
+Each of the `on` lines defines a new `belongs_to` association. That
+means you can customize just like always:
+
+```ruby
+on(:Team).belongs_to :team, resource: SomeCustomTeamResource do
+  # assign {}
+  # link {}
+  # ... etc ...
+end
+```
+
+
+  <h2 id="next">
+    <a href="/tutorial/step_9">
+      NEXT - 
+      <small>Step 9: Polymorphic Resources</small>
+      &raquo;
+    </a>
+  </h2>

data/docs/tutorial/step_9.md

@@ -0,0 +1,171 @@
+---
+title: 'Step 9'
+---
+
+### Step 9: Polymorphic Resources
+
+> [View the Diff](https://github.com/graphiti-api/employee_directory/compare/step_8_polymorphic_belongs_to...step_9_polymorphic_resource)
+
+In the last step, we covered polymorphic relationships: a single
+relationship can point to many different Resources. Polymorphic
+Resources are the same concept, without an association: a single
+Resource can resolve to many different sub-Resources. It's a very similar
+to [Single-Table Inheritance in ActiveRecord](https://api.rubyonrails.org/classes/ActiveRecord/Inheritance.html).
+
+To illustrate this, we'll add a `tasks` table and corresponding `Task` superclass. Each record in this table will resolve to one of `Bug`, `Epic`, or `Feature`.
+
+<table class="table table-small text-center">
+  <thead>
+    <tr>
+      <th class="text-center">id</th>
+      <th class="text-center">milestone_id</th>
+      <th class="text-center">type</th>
+      <th class="text-center">title</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td>null</td>
+      <td>Bug</td>
+      <td>Incorrect Value!</td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td>null</td>
+      <td>Feature</td>
+      <td>Build great stuff!</td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td>1</td>
+      <td>Epic</td>
+      <td>Build TONS of great stuff!</td>
+    </tr>
+  </tbody>
+</table>
+
+Why not just stick with a single `Task` model? Because each of these types has specific behavior: only `Feature`s have a `points` attribute, and only `Epic`s have a `milestones` relationship.
+
+### The Rails Stuff 🚂
+
+Let's create our `Task` model:
+
+```bash
+$ bin/rails g model Task employee:belongs_to team:belongs_to type:string
+title:string
+$ bin/rails db:migrate
+```
+
+And create models to reflect our STI logic:
+
+```ruby
+# app/models/task.rb
+class Task < ApplicationRecord
+  TYPES = %w(Bug Feature Epic)
+
+  belongs_to :team, optional: true
+  belongs_to :employee, optional: true
+end
+
+# app/models/bug.rb
+class Bug < Task
+end
+
+# app/models/feature.rb
+class Feature < Task
+end
+
+# Only Epics have Milestones
+# app/models/epic.rb
+class Epic < Task
+  has_many :milestones
+end
+
+# app/models/milestone.rb
+class Milestone < ApplicationRecord
+  belongs_to :epic
+end
+```
+
+Add the association:
+
+```ruby
+# app/models/team.rb
+has_many :tasks
+has_many :bugs
+has_many :features
+has_many :epics
+
+# app/models/employee.rb
+has_many :tasks
+has_many :bugs
+has_many :features
+has_many :epics
+```
+
+Finally [view the diff](https://github.com/graphiti-api/employee_directory/compare/step_8_polymorphic_belongs_to...step_9_polymorphic_resource) to edit your `seeds.rb` file.
+
+### The Graphiti Stuff 🎨
+
+Start by creating our Resource as normal:
+
+```bash
+$ bin/rails g graphiti:resource Task title:string
+```
+
+Now edit to support polymorphism and associations:
+
+```ruby
+class TaskResource < ApplicationResource
+  self.polymorphic = %w(FeatureResource BugResource EpicResource)
+
+  attribute :employee_id, :integer, only: [:filterable]
+  attribute :team_id, :integer, only: [:filterable]
+  attribute :title, :string
+
+  belongs_to :employee
+  belongs_to :team
+end
+```
+
+The point of this was to show how responses could be specific to type,
+so let's customize `Features`:
+
+```ruby
+class FeatureResource < TaskResource
+  attribute :points, :integer do
+    rand(20)
+  end
+end
+```
+
+
+Only Epics have milestones, but let's support those as well:
+
+```bash
+$ bin/rails g graphiti:resource Milestone name:string
+```
+
+```ruby
+class MilestoneResource < ApplicationResource
+  attribute :epic_id, :integer, only: [:filterable]
+  attribute :name, :string
+
+  # Customize the link to the Tasks endpoint, as we
+  # didn't create an Epics endpoint
+  belongs_to :epic do
+    link do |milestone|
+      helpers = Rails.application.routes.url_helpers
+      helpers.task_url(milestone.epic_id)
+    end
+  end
+end
+```
+
+#### Digging Deeper 🧐
+
+We can now resolve `Tasks`, either as a relationship or through the `/tasks` endpoint directly. When `Task` is type `'Feature'` it will have an extra attribute of `points`. When it's an `Epic`, it will have an additional relationship `Milestone`.
+
+Graphiti is smart enough to fetch the appropriate relationships. A hit
+to `/tasks?include=milestones` will only query for milestones when the resulting `Task` records are `Epic`s.