Graphiti

Graphiti is a resource-oriented framework that sits on top of your models (usually ActiveRecord) and exposes them via a JSON:API-compliant interface. It abstracts common concerns like serialization, filtering, sorting, pagination, and sideloading relationships, so you can build powerful APIs with minimal boilerplate. By defining resources instead of controllers and serializers, Graphiti helps you keep your API logic organized, consistent, and easy to maintain.

Examples

Here's an example resource from the example app just to give you a taste of the possibilities.

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

  sort :department_name, :string do |scope, value|
    scope.joins(current_position: :department)
      .merge(Department.order(name: value))
  end
end

In Rails, controllers serving resources include Graphiti::Rails::Controller. Putting it in ApplicationController covers the whole app; putting it in an API base class scopes it there and leaves the rest alone.

class ApplicationController < ActionController::Base
  include Graphiti::Rails::Controller
end

That gives those controllers the Graphiti context, the debugger, and JSON:API rendering for Graphiti's exceptions plus anything else raised. Registering your own exceptions does not require it — register_exception is available on every controller — but only controllers with the include render unregistered exceptions as JSON:API rather than falling through to Rails.

A pretty boilerplate controller that just interfaces with the resource. respond_with comes from the responders gem; with it in your Gemfile, add include Graphiti::Rails::Responders as well. Otherwise use render jsonapi: as the write actions below do.

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

Now you can query your endpoints simply and powerfully, like:

Request: http://localhost:3000/api/v1/employees?filter[title][eq]=Future Government Administrator&filter[age][lt]=40

JSON-API response

{
  "data": [
    {
      "id": "1",
      "type": "employees",
      "attributes": {
        "first_name": "Quinn",
        "last_name": "Homenick",
        "age": 36,
        "created_at": "2025-03-21T23:04:40+00:00",
        "updated_at": "2025-03-21T23:04:40+00:00"
      },
      "relationships": {
        "positions": {
          "links": {
            "related": "/api/v1/positions?filter[employee_id]=1"
          },
          "data": [
            {
              "type": "positions",
              "id": "1"
            },
            {
              "type": "positions",
              "id": "2"
            }
          ]
        },
        "tasks": {
          "links": {
            "related": "/api/v1/tasks?filter[employee_id]=1"
          }
        },
        "teams": {
          "links": {
            "related": "/api/v1/teams?filter[employee_id]=1"
          }
        },
        "notes": {
          "links": {
            "related": "/api/v1/notes?filter[notable_id]=1&filter[notable_type][eql]=Employee"
          }
        },
        "current_position": {
          "links": {
            "related": "/api/v1/positions?filter[current]=true&filter[employee_id]=1"
          },
          "data": {
            "type": "positions",
            "id": "1"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "1",
      "type": "positions",
      "attributes": {
        "title": "Future Government Administrator",
        "active": true
      },
      "relationships": {
        "employee": {
          "links": {
            "related": "/api/v1/employees/1"
          }
        },
        "department": {
          "links": {
            "related": "/api/v1/departments/3"
          }
        }
      }
    },
    {
      "id": "2",
      "type": "positions",
      "attributes": {
        "title": "Manufacturing Specialist",
        "active": false
      },
      "relationships": {
        "employee": {
          "links": {
            "related": "/api/v1/employees/1"
          }
        },
        "department": {
          "links": {
            "related": "/api/v1/departments/2"
          }
        }
      }
    }
  ],
  "meta": {}
}

Graphiti Documentation

Join the Discord