Graphiti

https://www.graphiti.dev/guides
Admin
Graphiti is an API framework that makes RESTful Resources a first-class concept, enabling efficient...
Tokens:38,351
Snippets:215
Trust Score:8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Graphiti from Scratch using Rails Template

Source: https://www.graphiti.dev/guides/getting-started/installation

Demonstrates installing Graphiti by using a remote Rails application template or a locally downloaded template. This method sets up a new Rails API application with Graphiti pre-configured.

```Shell
$ rails new blog --api -m https://raw.githubusercontent.com/graphiti-api/graphiti_rails_template/master/all.rb
```

```Shell
$ curl -O https://raw.githubusercontent.com/graphiti-api/graphiti_rails_template/master/all.rb
$ rails new blog --api -m all.rb
```

--------------------------------

### Add Graphiti Development Dependencies

Source: https://www.graphiti.dev/guides/getting-started/installation

Configures development and test dependencies for Graphiti using Bundler. Includes graphiti_spec_helpers, factory_bot_rails, rspec_rails, faker, and database_cleaner.

```ruby
group :development, :test do
  gem 'graphiti_spec_helpers'
  gem 'factory_bot_rails'
  gem 'rspec_rails'
  gem 'faker'
end

group :test do
  gem 'database_cleaner'
end
```

--------------------------------

### Define a Basic Graphiti Resource

Source: https://www.graphiti.dev/guides/getting-started/installation

Shows how to define a simple Graphiti Resource for an ActiveRecord model, specifying the adapter and attributes. This is a foundational step for integrating Graphiti with your data models.

```Ruby
# Assuming you already have a Post ActiveRecord Model
class PostResource < Graphiti::Resource
  self.adapter = Graphiti::Adapters::ActiveRecord
  attribute :title, :string
end

PostResource.all.data # => [#<Post>, #<Post>, ...]
```

--------------------------------

### Graphiti Configuration File (.graphiticfg.yml)

Source: https://www.graphiti.dev/guides/getting-started/installation

Explains the purpose and location of the `.graphiticfg.yml` file, which stores reusable configuration settings for Graphiti, such as the API namespace. It's essential for consistent behavior across generators and rake tasks.

```YAML
---
namespace: /my_api/v1
```

--------------------------------

### Configure RSpec with Graphiti Helpers

Source: https://www.graphiti.dev/guides/getting-started/installation

Sets up RSpec to use Graphiti spec helpers, FactoryBot syntax, and DatabaseCleaner for efficient test runs. It includes disabling Graphiti errors by default and managing database cleaning strategies.

```ruby
require 'graphiti_spec_helpers/rspec'

RSpec.configure do |config|
  config.include FactoryBot::Syntax::Methods
  config.include GraphitiSpecHelpers::RSpec
  config.include GraphitiSpecHelpers::Sugar

  # Raise errors during tests by default
  config.before :each do
    GraphitiErrors.disable!
  end

  # Clean your DB between test runs
  config.before(:suite) do
    DatabaseCleaner.strategy = :transaction
    DatabaseCleaner.clean_with(:truncation)
  end

  config.around(:each) do |example|
    begin
      DatabaseCleaner.cleaning do
        example.run
      end
    ensure
      DatabaseCleaner.clean
    end
  end
end
```

--------------------------------

### Graphiti Responders for JSONAPI, JSON, and XML

Source: https://www.graphiti.dev/guides/getting-started/installation

Illustrates how to use Graphiti's integration with the 'responders' gem to simplify rendering responses in different formats (JSONAPI, JSON, XML) from controller actions. This reduces boilerplate code for common rendering tasks.

```Ruby
# Manual rendering example
def index
  posts = PostResource.all(params)

  respond_to do |format|
    format.json { render(json: posts) }
    format.jsonapi { render(jsonapi: posts) }
    format.xml { render(xml: posts) }
  end
end

# Using responders gem
def index
  posts = PostResource.all(params)
  respond_with(posts)
end

# Gemfile
gem 'responders'

# app/controllers/application_controller.rb
include Graphiti::Responders
```

--------------------------------

### Configure Custom Pagination

Source: https://www.graphiti.dev/guides/getting-started/installation

Demonstrates how to configure Graphiti to use a custom pagination library, such as `will_paginate`, by overriding the default pagination behavior in `ApplicationResource`.

```ruby
# app/resources/application_resource.rb
paginate do |scope, current_page, per_page|
  scope.paginate(page: current_page, per_page: per_page)
end
```

--------------------------------

### Install RSpec

Source: https://www.graphiti.dev/guides/getting-started/installation

Installs RSpec for Rails projects using the Rails generator command.

```shell
$ bin/rails g rspec:install
```

--------------------------------

### Integrate Graphiti with Rails Controllers

Source: https://www.graphiti.dev/guides/getting-started/installation

Explains how to include Graphiti's Rails integration module in the ApplicationController to enable features like context access within resources. This makes Graphiti's functionality available across your API.

```Ruby
# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
  include Graphiti::Rails
end
```

--------------------------------

### Configure Graphiti Exception Handling

Source: https://www.graphiti.dev/guides/getting-started/installation

Details how to register custom exceptions with Graphiti for specific HTTP status codes, such as returning a 404 for RecordNotFound errors. It also shows how to use `handle_exception` for general error management.

```Ruby
# app/controllers/application_controller.rb
# When #show action does not find record, return 404
register_exception Graphiti::Errors::RecordNotFound,
  status: 404

rescue_from Exception do |e|
  handle_exception(e)
end
```

--------------------------------

### Backend Query Example

Source: https://www.graphiti.dev/guides/concepts/backends-and-models

Demonstrates a basic backend query mechanism accepting conditions and sort parameters. It illustrates the expected output format from a backend query.

```ruby
results = Backend.query \
  conditions: { name: 'Jane' },
  sort: { created_at: :asc }

results # [{ id: 1, name: 'Jane', rank: 83 }, ...]
```

--------------------------------

### Add Graphiti to Existing Rails App Gems

Source: https://www.graphiti.dev/guides/getting-started/installation

Specifies the necessary gems to add Graphiti to an existing Rails application. It includes the core 'graphiti' gem, 'kaminari' for pagination, and testing-specific gems like 'rspec-rails', 'factory_bot_rails', 'faker', and 'graphiti_spec_helpers'.

```Ruby
# The only strictly-required gem
gem 'graphiti'

# For automatic ActiveRecord pagination
gem 'kaminari'

# Test-specific gems
group :development, :test do
  gem 'rspec-rails'
  gem 'factory_bot_rails'
  gem 'faker'
  gem 'graphiti_spec_helpers'
end

group :test do
  gem 'database_cleaner'
end
```

--------------------------------

### Basic Graphiti Resource Setup

Source: https://www.graphiti.dev/guides/overview

Demonstrates the fundamental setup for a Graphiti resource, including routing, controller action, model definition, and resource configuration. This shows how to expose data via Graphiti.

```ruby
# config/routes.rb
resources :employees
```

```ruby
# app/controllers/employees_controller.rb
class EmployeesController < ApplicationController
  def index
    employees = EmployeeResource.all(params)
    respond_with(employees)
  end
end
```

```ruby
# app/models/employee.rb
class Employee < ApplicationRecord
end
```

```ruby
# app/resources/employee_resource.rb
class EmployeeResource < ApplicationResource
  attribute :name, :string
  attribute :age, :integer
end
```

--------------------------------

### Graphiti Adapter Overview

Source: https://www.graphiti.dev/guides/concepts/resources

Introduces the concept of Graphiti Adapters for packaging common resource overrides and using different datastores, referencing a cookbook for detailed examples.

```plaintext
Common resource overrides can be packaged into an Adapter for code re-use. The most common example is using a different client/datastore than ActiveRecord/RelationalDB.
[Adapters are best explained in our ‘Without ActiveRecord’ Cookbook](https://www.graphiti.dev/cookbooks/without-activerecord).
```

--------------------------------

### Graphiti Global Configuration

Source: https://www.graphiti.dev/guides/concepts/links

Configures global settings for the Graphiti library. This example shows how to enable 'links-on-demand', meaning links are only rendered when explicitly requested via a URL parameter.

```ruby
Graphiti.configure do |c|
  # Only render links when requested in the URL with '?links=true'
  c.links_on_demand = true
end
```

--------------------------------

### Implement Graphiti Model as PORO

Source: https://www.graphiti.dev/guides/concepts/backends-and-models

Provides an example of a Plain Old Ruby Object (PORO) implementation for a Graphiti model. This pattern uses `attr_accessor` for properties and a constructor to initialize the object, suitable for custom data sources.

```Ruby
class Employee
  attr_accessor :id,
    :first_name,
    :last_name,
    :age

  def initialize(attrs = {})
    attrs.each_pair { |k,v| send(:"#{k}=", v) }
  end
end
```

```Ruby
e = Employee.new(id: 1, first_name: 'Jane')
e.first_name # => 'Jane'
```

--------------------------------

### Deep Querying API Endpoint

Source: https://www.graphiti.dev/guides/concepts/remote-resources

Illustrates a deep querying example for fetching a Post resource along with its active comments, ordered by creation date. This represents a typical API request structure.

```apidoc
/posts?include=comments&sort=comments.created_at&filter[active]=true
```

--------------------------------

### Testing Sideloaded Resources

Source: https://www.graphiti.dev/guides/concepts/remote-resources

This example demonstrates testing the sideloading of related resources, specifically `Comment`s for a `Post`. It mocks an API response that includes sideloaded data and asserts that the associated resources are correctly loaded and mapped.

```ruby
describe 'sideloading' do
  describe 'comments' do
    include_context 'remote api'

    let!(:post) { create(:post) }

    let(:api_response) do
      {
        data: [{
          id: '789',
          type: 'comments',
          attributes: { body: 'hello' }
        }]
      }
    end

    before do
      params[:include] = 'comments'
    end

    it 'does something' do
      url = "http://my-api.com/api/v1/comments"
      url += "?filter[post_id]=#{post_id}"
      mock_api(url, api_response)
      render
      sl = d[0].sideload(:comments)
      expect(sl.map(&:id)).to eq(['789'])
      expect(sl.map(&:jsonapi_type).uniq)
      .to eq(['comments'])
    end
  end
end
```

--------------------------------

### Graphiti Resource Write Operations Setup

Source: https://www.graphiti.dev/guides/concepts/testing

Basic RSpec setup for testing Graphiti resource write operations, including creating and destroying resources.

```ruby
# spec/resources/employee/writes_spec.rb
require 'rails_helper'

RSpec.describe EmployeeResource, type: :resource do
  describe 'creating' do
    let(:payload) { ... }
    # ... code ...
  end

  describe 'creating' do
    let(:payload) { ... }
    # ... code ...
  end

  describe 'destroying' do
    # ... code ...
  end
end
```

--------------------------------

### Graphiti Schema Configuration Example

Source: https://www.graphiti.dev/guides/why

Illustrates a JSON schema configuration for a Graphiti resource, including default sorting. Changes to such configurations can be tracked for backwards-compatibility checks.

```json
{
  "name": "EmployeeResource",
  "type": "employees",
  "attributes": { ... },
  "default_sort": [{ "created_at": "desc" }]
}
```

```APIDOC
Schema Configuration:
  Resource: EmployeeResource
  Type: employees
  Default Sort:
    - created_at: desc

  Example Change Notification:
  EmployeeResource: default sort changed from [{:created_at=>"desc"}] to [{:last_name=>"asc"}].
```

--------------------------------

### Graphiti Remote Resource Query Example

Source: https://www.graphiti.dev/guides/concepts/remote-resources

This Ruby code demonstrates executing queries against a remote Graphiti resource. It shows how to fetch data with sorting and filtering parameters, such as `sort: '-id'` and `filter: { active: true }`. The results are returned as an array of OpenStruct objects, representing the data from the remote API.

```ruby
comments = CommentResource.all({
  sort: '-id',
  filter: { active: true }
})

# The model instances are OpenStructs
comments.data # => [#<OpenStruct>, #<OpenStruct>, ...]
```

--------------------------------

### Graphiti Resource Read Operations Testing Setup

Source: https://www.graphiti.dev/guides/concepts/testing

Basic RSpec setup for testing Graphiti resource read operations, including serialization, filtering, sorting, and sideloading.

```ruby
# spec/resources/employee/reads_spec.rb
require 'rails_helper'

RSpec.describe EmployeeResource, type: :resource do
  describe 'serialization' do
    # ... code ...
  end

  describe 'filtering' do
    # ... code ...
  end

  describe 'sorting' do
    # ... code ...
  end

  describe 'sideloading' do
    # ... code ...
  end
end
```

--------------------------------

### Graphiti Resource Query Configuration

Source: https://www.graphiti.dev/guides/concepts/resources

Provides a comprehensive example of configuring a Graphiti resource for querying. It includes defining filters, sorting, pagination, specifying a base scope for all queries, and implementing the resolution logic to execute the query.

```APIDOC
class PostResource < ApplicationResource
  # Define filtering logic for the 'title' attribute
  filter :title do |scope, value|
    eq do |scope, value|
      scope.where(title: value)
    end
  end

  # Define sorting logic for the 'title' attribute
  sort :title do |scope, dir|
    scope.order(title: dir)
  end

  # Define pagination logic
  paginate do |scope, current_page, per_page|
    scope.page(current_page).per(per_page)
  end

  # Define the initial scope for all queries
  def base_scope
    Post.all
  end

  # Define how to resolve the query and return model instances
  def resolve(scope)
    scope.to_a
  end
end

# Equivalent to:
# scope = Post.all # #base_scope
# if value = params[:filter].try(:[], :title)
#   scope = scope.where(title: value) # .filter
# end
# scope.to_a # #resolve
```

--------------------------------

### Graphiti Rails Integration

Source: https://www.graphiti.dev/guides/concepts/endpoints

Illustrates how Graphiti integrates with a Rails application. It shows the setup in routes, controller actions using Graphiti Resources, and the necessary mixin in the ApplicationController.

```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

class ApplicationController < ActionController::API
  include Graphiti::Rails

  # ... code ...
end
```

--------------------------------

### Graphiti Resource with Backend Adapter

Source: https://www.graphiti.dev/guides/concepts/backends-and-models

Demonstrates a simplified Graphiti Resource definition using a custom BackendAdapter. This approach abstracts away the manual mapping logic, making the resource definition cleaner when the backend interface is consistent.

```ruby
class EmployeeResource < ApplicationResource
  self.adapter = BackendAdapter
  attribute :name, :string
end
```

--------------------------------

### Basic Resource Definition

Source: https://www.graphiti.dev/guides/concepts/resources

Illustrates the minimal definition of a Graphiti resource, specifying an attribute and its type. This serves as a starting point before adding custom query logic.

```ruby
class PostResource < ApplicationResource
  attribute :title, :string
end
```

--------------------------------

### Graphiti Resource Endpoint Configuration

Source: https://www.graphiti.dev/guides/concepts/links

Illustrates how Graphiti associates Resources with URLs by default and how to configure the endpoint namespace and primary endpoints for resource routing.

```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
```

--------------------------------

### Graphiti Resource Implementation

Source: https://www.graphiti.dev/guides/concepts/backends-and-models

Illustrates how to define a Graphiti Resource, connecting it to a backend and mapping data. It shows setting the adapter, defining attributes, establishing a base scope, implementing filters and sorting, and resolving the final data using custom models.

```ruby
class EmployeeResource < ApplicationResource
  # We'll be coding the logic manually
  self.adapter = Graphiti::Adapters::Null

  attribute :name, :string

  # The blank scope we start with
  def base_scope
    { conditions: {}, sort: {}  }
  end

  # Merge filters into the hash based on request params
  filter :name do
    eq do |scope, value|
      scope[:conditions].merge!(value)
      scope
    end
  end

  # Set sort based on request params
  sort :name do |scope, direction|
    scope[:sort] = { name: direction }
    scope
  end

  # 'scope' here is our hash
  # We pass it to Backend.query, and return Models
  def resolve(scope)
    results = Backend.query(scope)
    results.map { |r| Employee.new(r) }
  end
end
```

--------------------------------

### Configuring Remote Resource Timeouts

Source: https://www.graphiti.dev/guides/concepts/remote-resources

Details how to customize the connection and read timeouts for requests made to remote APIs. This example sets `self.timeout` for read timeout and `self.open_timeout` for connection timeout on `CommentResource`.

```ruby
class CommentResource < ApplicationResource
  self.remote = "..."

  # Customize faraday timeout
  self.timeout = 10
  self.open_timeout = 20
end
```

--------------------------------

### Graphiti Endpoint Validation Example

Source: https://www.graphiti.dev/guides/concepts/links

Illustrates the consequence of endpoint validation. If a resource is accessed at an endpoint that is not associated with its definition, Graphiti raises an `InvalidEndpoint` error.

```ruby
class CommentsController < ApplicationController
  def index
    # Attempting to access PostResource via /comments endpoint
    # If PostResource is not configured for /comments, this will fail validation
    PostResource.all(params)
    # ...
  end
end
```

--------------------------------

### PORO Model Example

Source: https://www.graphiti.dev/guides/concepts/backends-and-models

Defines a Plain Old Ruby Object (PORO) to encapsulate data retrieved from a backend. This model includes attributes and business logic, such as checking if an employee is exemplary based on rank.

```ruby
class Employee
  attr_accessor :id, :name, :rank

  def initialize(attrs = {})
    attrs.each_pair { |k, v| send(:"#{k}=", v) }
  end

  def exemplary?
    rank > 80
  end
end
```

--------------------------------

### Graphiti Relationships and Sideloading

Source: https://www.graphiti.dev/guides/concepts/resources

Illustrates how Graphiti resources connect via relationships, enabling sideloading, links, and sideposting. It shows examples of `has_many` and `belongs_to` associations and how they map to underlying data fetching logic, similar to ActiveRecord's `.includes`.

```ruby
class PostResource < ApplicationResource
  has_many :comments
end

class CommentResource < ApplicationResource
  attribute :post_id, :integer, only: [:filterable]
  belongs_to :post
end

# Example usage:
# PostResource.all(include: 'comments')
# CommentResource.all(include: 'post')
```

--------------------------------

### Basic Data Mapping and Sideloading

Source: https://www.graphiti.dev/guides/concepts/remote-resources

Demonstrates how to map data from a remote API and sideload associated resources. It shows a simple Ruby snippet for mapping author data and a PostResource definition with a `has_many` association.

```ruby
comments.data.map(&:author) # => ["Jane Doe", "John Doe", ...]

class PostResource < ApplicationResource
  # Nothing to see here!
  has_many :comments
end
```

--------------------------------

### Graphiti Relationship Linking

Source: https://www.graphiti.dev/guides/concepts/links

Demonstrates how Graphiti automatically generates links for relationships and how to customize them using parameters or manual definitions. It also shows how to disable links.

```Ruby
class PostResource < ApplicationResource
  has_many :comments
end
```

```Ruby
has_many :comments do
  params do |hash|
    hash[:filter][:upvotes] = { gte: 100 }
  end
end
```

```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
```

```Ruby
has_many :comments, link: false
```

--------------------------------

### GraphQL Basic Resource Schema

Source: https://www.graphiti.dev/guides/why

Illustrates a fundamental GraphQL schema defining a resource (Employee) with basic CRUD operations. This serves as a starting point for API design, emphasizing resource identification.

```GraphQL
type Employee {
  id: ID!
  name: string
}

createEmployee(input: Employee): Employee
updateEmployee(input: Employee!): Employee
destroyEmployee(input: Employee!): Employee

employee(id: ID): Employee
```

--------------------------------

### Graphiti Polymorphic Resources

Source: https://www.graphiti.dev/guides/concepts/resources

Explains the concept of Polymorphic Resources in Graphiti, similar to ActiveRecord STI, where a single query can return multiple types of resources. Provides an example with `Employee` and `Task` models.

```APIDOC
Polymorphic Resources:
Enable a single query to return multiple Resource instances (e.g., Bugs, Features, Epics from a `/tasks` query).

Example Scenario:
Given ActiveRecord models:
class Employee < ApplicationRecord
  has_many :tasks
end

class Task < ApplicationRecord
  belongs_to :employee
  # ... other polymorphic associations ...
end

A query to `/tasks` could return different resource types based on the task's nature.
```

--------------------------------

### Graphiti Statistics Configuration

Source: https://www.graphiti.dev/guides/concepts/resources

Explains how to define and request statistics for resources, such as counts, averages, sums, and custom calculations. Includes examples for API requests and Ruby code for defining statistics.

```APIDOC
Requesting Statistics:
- Via Ruby:
  PostResource.all({
    stats: { total: 'count' }
  })
- Via API Query:
  /posts?stats[total]=count

Response Format:
{
  meta: {
    stats: {
      total: {
        count: 100
      }
    }
  }
}

Defining Statistics:
Use the `stat` method to define available statistics and their aggregation methods.

Examples:
stat total: [:count]
stat rating: [:average]
stat likes: [:sum]
stat score: [:maximum]

Custom Statistics:
Define custom logic for statistics using blocks.

Example:
stat rating: [:average] do
  standard_deviation do |scope, attr|
    # your standard deviation code here
  end
end
```

--------------------------------

### Graphiti Rake Tasks

Source: https://www.graphiti.dev/guides/concepts/debugging

Introduces the availability of rake tasks for common debugging scenarios, suggesting that these tasks provide convenient patterns for frequent debugging needs.

```shell
# Example: graphiti:request
# Example: graphiti:benchmark
```

--------------------------------

### Graphiti Debugger Usage

Source: https://www.graphiti.dev/guides/concepts/debugging

Demonstrates how to use the Graphiti debugger to inspect queries executed for a request. It shows how to access resources directly and test them in a Rails console, mirroring how Graphiti interacts with resources.

```ruby
employees = EmployeeResource.all
PositionResource.all(filter: { employee_id: employees.map(&:id) })
```

```shell
$ bin/rails c
>> TeamResource.all({:filter=>{:department_id=>"1,2,3"}})
```

--------------------------------

### Execute Graphiti Request for Debugging

Source: https://www.graphiti.dev/guides/concepts/debugging

Executes a request using ActionDispatch::Integration::Session for debugging without a live web server. Supports an optional debug flag and environment variables for authorization headers.

```bash
bin/rake graphiti:request[/employees]
# Example with debug enabled:
bin/rake graphiti:request[/employees,true]
# Example with authorization header:
export AUTHORIZATION_HEADER="Token --PRIVATE_API_KEY--"
bin/rake graphiti:request[/employees,true]
```

--------------------------------

### Graphiti #resolve Method Override

Source: https://www.graphiti.dev/guides/concepts/resources

Explains how to override the `#resolve` method in a resource to customize query execution and return values. Provides an example of logging before and after query execution.

```APIDOC
Overriding #resolve:
Implement `#resolve` to control query execution and model instance retrieval.

Requirements:
1. Execute the query.
2. Return an array of `Model` instances.

Example Override:
def resolve(scope)
  Rails.logger.info "begin resolving scope..."
  result = super
  Rails.logger.info "resolved!"
  result
end
```

--------------------------------

### Implement Graphiti Model with ActiveModel::Model

Source: https://www.graphiti.dev/guides/concepts/backends-and-models

Shows how to implement a Graphiti model using ActiveModel::Model, which provides a convenient abstraction over POROs. It includes `attr_accessor` for properties and inherits ActiveModel features.

```Ruby
class Employee
  include ActiveModel::Model

  attr_accessor :id,
    :first_name,
    :last_name,
    :age
end
```

```Ruby
e = Employee.new(id: 1, first_name: 'Jane')
e.first_name # => 'Jane'
```

--------------------------------

### API Request Helpers

Source: https://www.graphiti.dev/guides/concepts/testing

Provides JSONAPI-compliant request methods for API testing, ensuring correct headers (`application/vnd.api+json`) and payload serialization. Includes methods for GET, POST, PUT, PATCH, and DELETE.

```APIDOC
jsonapi_get(url, params:)
jsonapi_post(url, payload)
jsonapi_put(url, payload)
jsonapi_patch(url, payload)
jsonapi_delete(url)
```

--------------------------------

### Graphiti Relationship Link Generation

Source: https://www.graphiti.dev/guides/concepts/links

Manually defines how to generate a link for a specific relationship. This allows for custom URL construction based on the resource instance and available helpers.

```ruby
has_many :comments do
  link do |post|
    # Use Rails URL helpers to construct the link dynamically
    helpers = Rails.application.routes.url_helpers
    helpers.comments_url(params: { filter: { post_id: post.id } })
    # Alternatively, provide a hardcoded URL structure
    # "http://example.com/api/v1/comments?filter[post_id]=#{post.id}"
  end
end
```

--------------------------------

### Querying Remote Resources with Graphiti

Source: https://www.graphiti.dev/guides/concepts/remote-resources

This Ruby code illustrates how Graphiti handles querying and eager-loading of data from remote resources. It shows fetching posts and then querying associated comments using filters, demonstrating the underlying mechanism for cross-service data retrieval. The data returned from remote resources are typically OpenStruct objects.

```ruby
# under the hood
posts = PostResource.all.data
CommentResource.all(filter: { post_id: 123 })
```

--------------------------------

### Benchmark Graphiti Requests

Source: https://www.graphiti.dev/guides/concepts/debugging

Runs a quick benchmark to measure average response time without hitting a live web server. This helps eliminate latency variations when assessing performance.

```bash
bin/rake graphiti:benchmark[/employees,100]
```

--------------------------------

### Graphiti Debugging Configuration

Source: https://www.graphiti.dev/guides/concepts/debugging

Details how to configure Graphiti's debugging behavior, including explicitly toggling debugging, enabling verbose model logging, and assigning custom loggers. Configuration can be done via initializer files or environment variables.

```ruby
# config/initializers/graphiti.rb
Graphiti.configure do |c|
  c.debug = false
end

# Or use environment variable
# GRAPHITI_DEBUG=false
```

```ruby
# config/initializers/graphiti.rb
Graphiti.configure do |c|
  c.debug_models = true
end

# Or use environment variable
# GRAPHITI_DEBUG_MODELS=true
```

```ruby
# app/controllers/application_controller.rb
def allow_graphiti_debug_json?
  true
  # or, current_user.admin?
  # or, Rails.env.development?
end
```

```ruby
Graphiti.logger = Logger.new(...)

# Or the built-in STDOUT logger:
Graphiti.logger = Graphiti.stdout_logger
```

```ruby
Graphiti::Debugger.debug do
  EmployeeResource.all
end
```

--------------------------------

### Graphiti Persistence Methods (Create, Update, Destroy)

Source: https://www.graphiti.dev/guides/concepts/resources

Provides Ruby code examples for overriding Graphiti's default persistence methods (`create`, `update`, `destroy`). These methods handle saving data to the database and should return the model instance. It's recommended to use hooks instead of direct overrides.

```Ruby
# app/resources/employee_resource.rb

def create(attributes)
  employee = Employee.new
  attributes.each_pair do |key, value|
    employee.send(:"#{key}=", value)
  end
  employee.save
  employee
end

def update(attributes)
  employee = EmployeeResource.find(attributes.delete(:id)).data
  attributes.each_pair do |key, value|
    employee.send(:"#{key}=", value)
  end
  employee.save
  employee
end

def destroy(attributes)
  employee = EmployeeResource.find(attributes.delete(:id)).data
  employee.destroy
  employee
end
```

--------------------------------

### Implement Graphiti Model with Dry::Struct

Source: https://www.graphiti.dev/guides/concepts/backends-and-models

Demonstrates implementing a Graphiti model using `Dry::Struct`, a modern approach for defining data structures with type checking. This leverages the `dry-types` gem, a dependency of Graphiti.

```Ruby
module Types
  include Dry::Types.module
end

class Employee < Dry::Struct
  attribute :id, Types::Integer
  attribute :first_name, Types::String
  attribute :last_name, Types::Integer
  attribute :age, Types::Integer
end
```

```Ruby
e = Employee.new(id: 1, first_name: 'Jane')
e.first_name # => 'Jane'
```

--------------------------------

### Customizing Resource Base Scope via Endpoints

Source: https://www.graphiti.dev/guides/concepts/endpoints

Explains how endpoints can customize the base scope of a Resource, creating a specific starting point for queries. This allows for variations like '/posts' and '/top_posts' using the same underlying Resource logic.

```ruby
def index
  base_scope = Post.where("upvotes > ?", 100)
  posts = PostResource.all(params, base_scope)
  respond_with(posts)
end
```

--------------------------------

### Install Vandal UI via Gem in Rails Routes

Source: https://www.graphiti.dev/guides/vandal

This snippet demonstrates how to integrate the Vandal UI into a Ruby on Rails application by adding the `vandal_ui` gem and mounting its engine in the routes file. This makes the UI accessible for exploring Graphiti APIs.

```ruby
# config/routes.rb
scope path: ApplicationResource.endpoint_namespace, defaults: { format: :jsonapi } do
  # ... routes ...
  mount VandalUi::Engine, at: '/vandal'
end
```

--------------------------------

### Graphiti Resource Endpoint Configuration

Source: https://www.graphiti.dev/guides/concepts/links

Defines how a Graphiti Resource is exposed via API endpoints. This includes setting a primary endpoint with specific actions, altering the endpoint path, defining secondary endpoints for alternative access, and setting a namespace for all endpoints associated with the resource.

```ruby
class PostResource < ApplicationResource
  # Set a namespace for all endpoints associated with this resource
  self.endpoint_namespace = '/api/v1'

  # Define the primary endpoint for this resource, specifying allowed actions
  primary_endpoint '/posts', [:index, :show]

  # Alternatively, alter only the endpoint path
  # self.endpoint[:path] = '/posts'

  # Alternatively, alter only the actions supported by the primary endpoint
  # self.endpoint[:actions] = [:index, :show]

  # Define a secondary endpoint for accessing the resource, with specific actions
  secondary_endpoint '/top_posts', [:index]
end
```

--------------------------------

### Debug Resource Calls with Pry

Source: https://www.graphiti.dev/guides/concepts/debugging

Overrides the `resolve` method in a Graphiti resource to insert a `binding.pry` call. This allows for direct debugging of individual resource calls and scopes before a query is executed.

```ruby
def resolve(scope)
  binding.pry
end
```

--------------------------------

### Define Base Scope in PostResource

Source: https://www.graphiti.dev/guides/upgrading

Example of defining a base scope for a resource in Graphiti. This method is used to scope queries, and it's recommended to use `params` for manual sideloading logic instead.

```ruby
def base_scope
  Post.active
end
```

--------------------------------

### Graphiti Configuration Flags

Source: https://www.graphiti.dev/guides/concepts/links

Controls core Graphiti behaviors. `autolink` determines if links are automatically generated for relationships, and `validate_endpoints` enforces that links point to valid, accessible endpoints.

```ruby
class ApplicationResource < Graphiti::Resource
  # Turn off automatically generated links for relationships
  self.autolink = false

  # Turn off endpoint validation to allow links to potentially non-existent endpoints
  self.validate_endpoints = false
end
```

--------------------------------

### Remote Error Handling Strategy

Source: https://www.graphiti.dev/guides/concepts/remote-resources

Explains how to handle errors originating from remote API calls. It demonstrates using `rescue_from` to catch exceptions and conditionally display raw error details based on user privileges, wrapping remote errors in `Graphiti::Errors::Remote`.

```ruby
rescue_from Exception do |e|
  handle_exception(e,  show_raw_error: current_user.developer?)
end
```

--------------------------------

### Integrate ActiveModel Validations

Source: https://www.graphiti.dev/guides/concepts/backends-and-models

Explains how to enable Graphiti's validation functionality by ensuring your model includes ActiveModel::Validations. This allows Graphiti to leverage model validation logic and return JSONAPI-compliant error payloads.

```Ruby
model.valid?
object.errors.messages.each_pair { ... }
```

```Ruby
class Employee
  include ActiveModel::Validations
end
```

--------------------------------

### Customizing Remote Request Logic

Source: https://www.graphiti.dev/guides/concepts/remote-resources

Shows how to intercept and modify the request process for remote resources. The `make_request` method in `CommentResource` allows for custom logic, such as adding headers, before the request is sent via Faraday.

```ruby
class CommentResource < ApplicationResource
  self.remote = "..."

  def make_request(url)
    # request here is from Faraday:
    #
    # conn.get do |req|
    #   yield req
    # end
    #
    super do |request|
      request.headers["Custom"] = "Header"
    end
  end
end
```

--------------------------------

### Mocking Remote API Requests

Source: https://www.graphiti.dev/guides/concepts/remote-resources

This snippet shows how to mock a remote API request and response for testing. It utilizes `include_context 'remote api'` and `mock_api` to simulate the API's behavior, allowing tests to verify the correct URL is called and the response is processed.

```ruby
describe 'comments' do
  include_context 'remote api'

  let(:api_response) do
    {
      data: [{
        id: '1',
        type: 'comments',
        attributes: { body: 'hello' }
      }]
    }
  end

  it 'does something' do
    url = 'http://my-api.com/api/v1/comments?page[size]=999'
    mock_api(url, api_response)
    # ... test ...
  end
end
```

--------------------------------

### Graphiti Resource with Association

Source: https://www.graphiti.dev/guides/concepts/remote-resources

This Ruby code defines a `PostResource` inheriting from `ApplicationResource` and includes a `has_many` association to `comments`. This sets up the basic structure for resource management within Graphiti, enabling lazy loading of related data. It serves as a foundation for defining resource behavior and relationships.

```ruby
class PostResource < ApplicationResource
  has_many :comments
end
```

--------------------------------

### Customizing Remote Attribute Display

Source: https://www.graphiti.dev/guides/concepts/remote-resources

Explains how to override the default attribute handling for remote resources. This example customizes the display of the `body` attribute for `CommentResource`, truncating it to 100 characters.

```ruby
class CommentResource < ApplicationResource
  self.remote = "http://my-api.com/api/v1/comments"

  attribute :body, :string do
    @object.body.truncate(100)
  end
end
```

--------------------------------

### Graphiti Resource Querying

Source: https://www.graphiti.dev/guides/concepts/endpoints

Demonstrates how to query a Graphiti Resource with various parameters like filters, sorting, pagination, and eager loading. It also shows how to process the results.

```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: [{ ... }] }
```

--------------------------------

### PositionResource Filterable Attribute

Source: https://www.graphiti.dev/guides/concepts/resources

Example of defining an attribute in a Graphiti resource to be filterable, specifically `employee_id` for the `PositionResource`.

```ruby
class PositionResource < ApplicationResource
  attribute :employee_id, :integer, only: [:filterable]
  # ... code ...
end
```

--------------------------------

### Limit Sort Directions

Source: https://www.graphiti.dev/guides/concepts/resources

Restricts the allowed sorting directions for a specific attribute. For example, `only: [:desc]` permits only descending order.

```ruby
sort :name, only: [:desc]
```

--------------------------------

### Faux has_one Model Definition

Source: https://www.graphiti.dev/guides/concepts/resources

Example of an ActiveRecord model (`Employee`) defining a `has_many` and a `has_one` relationship, where `current_position` is scoped to the latest `created_at`.

```ruby
# app/models/employee.rb
has_many :positions
has_one :current_position, -> { where(created_at: :desc) }, class_name: 'Position'
```

--------------------------------

### Limit Filter Operators

Source: https://www.graphiti.dev/guides/concepts/resources

Restricts the allowed operators for a filter using `only` or `except`. For example, `only: [:eq, :suffix]` permits only equality and suffix matching.

```ruby
filter :name, :string, only: [:eq, :suffix]
```

--------------------------------

### Generate Graphiti Resource with Rails

Source: https://www.graphiti.dev/guides/concepts/resources

Demonstrates how to use the `rails generate graphiti:resource` command to create a new Graphiti resource. It shows basic usage, attribute definition, and limiting supported actions.

```Shell
$ rails generate graphiti:resource NAME [attribute:type] [options]

$ rails generate graphiti:resource Employee first_name:string age:integer

$ rails generate graphiti:resource Employee -a index show
```

--------------------------------

### Graphiti Resource Configuration Defaults

Source: https://www.graphiti.dev/guides/concepts/resources

Illustrates common higher-level configuration options for Graphiti resources, including model, type, primary endpoints, default sorting, and pagination size.

```APIDOC
Resource Configuration:
Set properties like `model`, `type`, `primary_endpoint`, `default_sort`, and `default_page_size`.

Example Resource Definition:
class PostResource < ApplicationResource
  self.model = Post
  self.type = 'posts'

  # Used for Links
  primary_endpoint '/posts', [:index, :show, :create, :update, :destroy]

  # Default nil
  self.default_sort = [{ title: :asc }]

  # Default 20
  self.default_page_size = 10
end
```

--------------------------------

### Defining Remote Resource with Association

Source: https://www.graphiti.dev/guides/concepts/remote-resources

Shows how to define a `CommentResource` that connects to a remote API endpoint. It specifies the remote base URL and defines a `belongs_to` association to an `AuthorResource`.

```ruby
class CommentResource < ApplicationResource
  self.remote = "http://my-api.com/api/v1/comments"

  belongs_to :author
end
```

--------------------------------

### Graphiti Resource and API Testing Commands

Source: https://www.graphiti.dev/guides/upgrading

Commands provided by Graphiti to generate test files for API resources. These commands help in setting up the testing environment and migrating legacy specs.

```APIDOC
Generate API Test:
  `rails g graphiti:api_test PostResource`

Generate Resource Test:
  `rails g graphiti:resource_test PostResource`
```

--------------------------------

### RSpec: Test Resource Filtering by Title

Source: https://www.graphiti.dev/guides/concepts/testing

Illustrates how to test resource filtering in RSpec, specifically filtering employees by title. It uses the shared context for data setup and asserts that the correct records are returned after applying the filter parameters.

```ruby
# spec/resources/employee_resource.rb
describe 'filtering' do
  describe 'by title' do
    include_context 'employees by title'

    before do
      params[:filter] = { title: 'bar' }
    end

    it 'returns employees matching the given title'
      expect(records).to eq([employee2, employee3])
    end
  end
end
```

--------------------------------

### Querying Data with Resource Proxy

Source: https://www.graphiti.dev/guides/concepts/resources

Shows how to query data using a Graphiti resource, returning a proxy object similar to ActiveRecord::Relation. Demonstrates methods like `.all`, `.find`, and how to access data and render different formats (JSON:API, JSON, XML).

```APIDOC
# Querying with parameters
EmployeeResource.all({
  filter: { first_name: 'Jane' },
  sort: '-created_at',
  page: { size: 10, number: 2 }
})

# Accessing data and rendering
employees = EmployeeResource.all
employees.data # => [#<Employee>, #<Employee>, ...]
employees.to_jsonapi
employees.to_json
employees.to_xml

# Finding a single record
employee = EmployeeResource.find(id: 123)
employee.data.first_name # => "Jane"
```

--------------------------------

### Customizing Remote Request Headers

Source: https://www.graphiti.dev/guides/concepts/remote-resources

Provides a method to override or add custom headers to requests sent to remote APIs. The `request_headers` method in `CommentResource` demonstrates how to set a specific custom header.

```ruby
# app/resources/comment_resource.rb
def request_headers
  { "Some-Foo" => "bar" }
end
```

--------------------------------

### FactoryBot Factory Definition with Faker

Source: https://www.graphiti.dev/guides/concepts/testing

Illustrates defining a FactoryBot factory for an Employee model, utilizing Faker for randomized data generation and demonstrating how to handle `belongs_to` associations to ensure related data is seeded correctly.

```Ruby
# BEFORE
FactoryBot.define do
  factory :employee do
    first_name { 'MyString' }
  end
end

# AFTER
FactoryBot.define do
  factory :employee do
    first_name { Faker::Name.first_name }
  end
end

# Handling associations
FactoryBot.define do
  factory :employee do
    department
    # OR association :department, factory: :department
  end
end
```
Tokens:
Raw