Graphiti

To expose a model via Graphiti, create a class that inherits from ApplicationResource. Within this class, you define attributes, relationships, filters, and sorts.

Key features include:

• attribute: Defines a field, its type, and whether it is writable or has specific capabilities like filterable or sortable.
• has_many, has_one, many_to_many, and polymorphic_has_many: Define relationships between resources.
• params: A block used within a relationship to inject specific parameters (e.g., applying a filter to a related resource).
• filter: Custom logic to handle complex queries.
• sort: Custom logic to handle complex ordering.

class EmployeeResource < ApplicationResource
  attribute :first_name, :string
  attribute :last_name, :string
  attribute :age, :integer
  attribute :created_at, :datetime, writable: false
  attribute :updated_at, :datetime, writable: false
  attribute :title, :string, only: [:filterable, :sortable]

  has_many :positions
  has_many :tasks
  many_to_many :teams
  polymorphic_has_many :notes, as: :notable
  
  has_one :current_position, resource: PositionResource do
    params do |hash|
      hash[:filter][:current] = true
    end
  end

  filter :title, only: [:eq] do
    eq do |scope, value|
      scope.joins(:current_position).merge(Position.where(title: value))
    end
  end

  sort :title do |scope, value|
    scope.joins(:current_position).merge(Position.order(title: value))
  end
end

Graphiti resources are designed to work with minimal boilerplate in your controllers. You use the resource class to fetch, build, or find records based on the incoming params.

Common patterns:

• Index: Use Resource.all(params) to retrieve a collection.
• Show: Use Resource.find(params) to retrieve a single record.
• Create: Use Resource.build(params) to instantiate a new record.
• Update: Use Resource.find(params) followed by update_attributes.
• Destroy: Use Resource.find(params) followed by destroy.

When rendering, use render jsonapi: resource for successful operations and render jsonapi_errors: resource for handling validation errors.

class EmployeesController < ApplicationController
  def index
    employees = EmployeeResource.all(params)
    respond_with(employees)
  end

  def show
    employee = EmployeeResource.find(params)
    respond_with(employee)
  end

  def create
    employee = EmployeeResource.build(params)

    if employee.save
      render jsonapi: employee, status: 201
    else
      render jsonapi_errors: employee
    end
  end

  def update
    employee = EmployeeResource.find(params)

    if employee.update_attributes
      render jsonapi: employee
    else
      render jsonapi_errors: employee
    end
  end

  def destroy
    employee = EmployeeResource.find(params)

    if employee.destroy
      render jsonapi: { meta: {} }, status: 200
    else
      render jsonapi_errors: employee
    end
  end
end

Graphiti uses the Graphiti::RequestValidators::Validator to process incoming request payloads. Even read requests currently pass through this validator.

When a payload is validated, the validator performs the following steps:

1. Deserialization: It uses Graphiti::Deserializer to parse the parameters.
2. Type Checking: It ensures the data.type is present. If the resource is polymorphic, it resolves the correct resource type based on the payload's meta[:type].
3. Attribute Typecasting: It iterates through attributes and attempts to typecast them using the resource's typecast method. It catches and records errors for UnknownAttribute, InvalidAttributeAccess (unwritable), and TypecastFailed.
4. Relationship Processing: It validates that requested relationships are defined as sideload on the resource and checks if they are writable before proceeding with nested processing.

Key Validation Rules:

• ID Validation: The :id attribute is only validated if the action is :create. For other actions, it is used strictly for lookup.
• Error Reporting: Errors are collected into a Graphiti::Util::SimpleErrors object, using fully qualified keys (e.g., data.relationships.name.attributes.key) to pinpoint the location of the error in the payload.

Graphiti allows you to control how relationships (sideloads) are fetched and whether they are processed concurrently.

Concurrency and Database Connection Pool

When concurrency is set to true, Graphiti uses a global executor to fetch sideloads asynchronously. This requires careful management of your database connection pool.

Important: Your database connection pool size (configured in database.yml) must be large enough to accommodate both your foreground threads (web server/job workers) and the background threads used by Graphiti.

To avoid connection exhaustion, your pool size should be at least: thread_count + concurrency_max_threads + 1

Example: If your web server has 3 threads and concurrency_max_threads is 4, your pool size should be at least 8.*

Graphiti.configure do |config|
  config.raise_on_missing_sideload = true # Defaults to true
  config.concurrency = true             # Defaults to false
  config.concurrency_max_threads = 4     # Defaults to 4
end