jpie 0.4.5 → 1.0.1

data/README.md

@@ -1,227 +1,1599 @@
-# JPie
+# JSONAPI
 
-[![Gem Version](https://badge.fury.io/rb/jpie.svg)](https://badge.fury.io/rb/jpie)
-[![Build Status](https://github.com/emilkampp/jpie/workflows/CI/badge.svg)](https://github.com/emilkampp/jpie/actions)
+A Rails 8+ gem that provides JSON:API compliant routing DSL and generic JSON:API controllers for producing and consuming JSON:API resources.
 
-JPie is a modern, lightweight Rails library for developing JSON:API compliant servers. It focuses on clean architecture with strong separation of concerns and extensibility.
+## Features
 
-## Key Features
-
-✨ **Modern Rails DSL** - Clean, intuitive syntax following Rails conventions  
-🔧 **Method Overrides** - Define custom attribute methods directly on resource classes  
-🎯 **Smart Inference** - Automatic model and resource class detection  
-⚡ **Powerful Generators** - Scaffold resources with relationships, meta attributes, and automatic inference  
-📊 **Polymorphic Support** - Full support for complex polymorphic associations  
-🔄 **STI Ready** - Single Table Inheritance works out of the box  
-🔗 **Through Associations** - Full support for Rails `:through` associations  
-⚡ **Performance Optimized** - Efficient serialization with intelligent deduplication  
-🛡️ **Authorization Ready** - Built-in scoping support for security  
-📋 **JSON:API Compliant** - Full specification compliance with sorting, includes, and meta  
-🚨 **Robust Error Handling** - Smart inheritance-aware error handling with full customization options
+- JSON:API v1.1 compliant routing and controllers
+- Automatic MIME type registration (`application/vnd.api+json`)
+- Generic resource controller with CRUD operations
+- Built-in serialization and deserialization
+- Support for filtering (explicit filters with column-aware operators), sorting, pagination, sparse fieldsets, and includes
+- Relationship endpoints for managing resource relationships independently
+- Separate creatable and updatable field definitions
+- Configurable pagination options
+- Content negotiation with Accept and Content-Type headers
+- Support for polymorphic and STI relationships
 
 ## Installation
 
-Add JPie to your Rails application:
-
 ```bash
 bundle add jpie
 ```
 
-## Development Setup
+## Requirements
 
-This project uses [Overcommit](https://github.com/sds/overcommit) to enforce code quality through Git hooks. After cloning the repository:
+- Ruby >= 3.4.0
+- Rails >= 8.0.0
 
-### Quick Setup (Recommended)
+## Routing
 
-```bash
-# One command to set up everything
-./bin/setup-hooks
+Use the `jsonapi_resources` DSL in your routes file to create standard RESTful routes (index, show, create, update, destroy) that default to the `json_api/resources` controller and `jsonapi` format:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  jsonapi_resources :users
+  jsonapi_resources :posts
+end
 ```
 
-### Manual Setup
+To use a custom controller instead of the default:
 
-If you prefer to set up manually:
+```ruby
+jsonapi_resources :users, controller: "api/users"
+```
 
-```bash
-# 1. Install dependencies
-bundle install
+## Resource Definitions
+
+Define resource classes to control which attributes and relationships are exposed via the JSON:API endpoint:
+
+```ruby
+# app/resources/user_resource.rb
+class UserResource < JSONAPI::Resource
+  attributes :email, :name, :phone
+
+  has_many :posts
+  has_one :profile
+end
+```
 
-# 2. Install overcommit globally (one-time setup)
-gem install overcommit
+### Virtual Attributes
 
-# 3. Install the Git hooks for this project
-overcommit --install
+To create a virtual attribute, declare it in `attributes` and implement a getter method:
 
-# 4. Sign the configuration (required for security)
-overcommit --sign
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :name, :email, :full_name
+
+  # Virtual attribute getter
+  def full_name
+    "#{resource.name} (#{resource.email})"
+  end
+end
 ```
 
-### 3. Automated Quality Checks
+The getter method receives the underlying model instance via `resource`. Virtual attributes are serialized just like regular attributes and appear in the response:
 
-The following checks run automatically:
+```json
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "attributes": {
+      "name": "John Doe",
+      "email": "john@example.com",
+      "full_name": "John Doe (john@example.com)"
+    }
+  }
+}
+```
 
-**Pre-commit hooks:**
-- ✅ **RuboCop** - Code style and quality analysis
-- ✅ **Trailing whitespace** - Prevents whitespace issues
-- ✅ **Merge conflicts** - Catches unresolved conflicts
+You can also define setters for virtual attributes that transform incoming values into real model attributes:
 
-**Pre-push hooks:**
-- ✅ **RSpec** - Full test suite execution
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :name, :email, :display_name
+  creatable_fields :name, :email, :display_name
+  updatable_fields :name, :display_name
 
-### 4. Manual Quality Checks
+  def initialize(resource = nil, context = {})
+    super
+    @transformed_params = {}
+  end
 
-You can run these checks manually:
+  # Setter that transforms virtual attribute to model attribute
+  def display_name=(value)
+    @transformed_params["name"] = value.upcase
+  end
 
-```bash
-# Run RuboCop with auto-fix
-bundle exec rubocop -A
+  # Getter for the virtual attribute (for serialization)
+  def display_name
+    resource&.name&.downcase
+  end
+
+  # Return transformed params accumulated by setters
+  def transformed_params
+    @transformed_params || {}
+  end
+end
+```
+
+When a client sends `display_name` in a create or update request, the setter transforms it to `name` (uppercase). The virtual attribute `display_name` is automatically excluded from the final params returned by the deserializer, so it won't be passed to the model.
+
+**Important**: You must initialize `@transformed_params` in your `initialize` method if you use setters that modify it.
+
+### Creatable and Updatable Fields
+
+By default, all attributes are available for both create and update. Restrict fields per operation:
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :name, :email, :phone, :role
+
+  creatable_fields :name, :email, :phone  # role is system-set
+  updatable_fields :name, :phone          # email is immutable
+end
+```
+
+## Relationship Endpoints
+
+Manage relationship links independently of the parent resource. This will not delete the related resource itself, but only manage the relationship.
+
+If the relationship is `User -(has_one)-> AccountUser -(belong_to)-> Account` and we DELETE `/users/1/relationships/account` this will not delete the account, but delete the account user.
+
+- `GET /users/:id/relationships/:relationship_name` - Show relationship linkage
+- `PATCH /users/:id/relationships/:relationship_name` - Replace relationship linkage
+- `DELETE /users/:id/relationships/:relationship_name` - Remove relationship linkage
+
+## Filtering
+
+Declare permitted filters in your resource class:
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :name, :email, :phone
+  filters :name_eq, :name_match, :created_at_gte
+end
+```
+
+Filters ending in `_eq`, `_match`, `_lt`, `_lte`, `_gt`, or `_gte` are applied to the corresponding column:
+
+```
+GET /users?filter[name_eq]=John
+GET /users?filter[created_at_gte]=2024-01-01
+```
 
-# Run tests
-bundle exec rspec
+Filter through relationships by nesting the filter key:
 
-# Test hooks without committing
-overcommit --run pre-commit
-overcommit --run pre-push
 ```
+GET /posts?filter[user][email]=jane@example.com
+GET /comments?filter[post][user][id]=123
+```
+
+To pass multiple values, use bracket notation:
+
+```
+GET /users?filter[roles][]=admin&filter[roles][]=editor
+```
+
+## Pagination
+
+Paginate collections with `page[number]` and `page[size]`:
+
+```
+GET /users?page[number]=1&page[size]=10
+GET /users?page[number]=2&page[size]=25
+```
+
+Paginated responses include a `links` object with `self`, `first`, `last`, and conditional `prev`/`next` URLs, plus `meta.total` with the full count:
+
+```json
+{
+  "data": [...],
+  "links": {
+    "self": "/users?page[number]=2&page[size]=10",
+    "first": "/users?page[number]=1&page[size]=10",
+    "last": "/users?page[number]=5&page[size]=10",
+    "prev": "/users?page[number]=1&page[size]=10",
+    "next": "/users?page[number]=3&page[size]=10"
+  },
+  "meta": { "total": 42 }
+}
+```
+
+Default page size is 25, maximum is 100 (configurable).
 
-## Quick Start
+## Includes
 
-JPie works out of the box with minimal configuration:
+Include related resources with the `include` parameter:
 
-### 1. Create Your Model
+```
+GET /users?include=posts
+GET /users?include=posts,comments
+GET /users?include=posts.comments.author
+```
+
+Nested includes use dot notation and support arbitrary depth. Related resources appear in the `included` array, and relationships reference them by `type` and `id`:
+
+```json
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "relationships": {
+      "posts": {
+        "data": [{ "type": "posts", "id": "5" }]
+      }
+    }
+  },
+  "included": [
+    {
+      "type": "posts",
+      "id": "5",
+      "attributes": { "title": "Hello World" }
+    }
+  ]
+}
+```
+
+## Polymorphic Relationships
+
+Polymorphic relationships are accessed through the parent resource's relationship endpoints and includes. Route only the parent resource; the gem automatically handles polymorphic types through the relationship endpoints.
+
+```ruby
+# config/routes.rb
+jsonapi_resources :users
+```
+
+The user model declares a polymorphic `belongs_to`:
 
 ```ruby
 class User < ActiveRecord::Base
-  validates :name, presence: true
-  validates :email, presence: true, uniqueness: true
-  
-  has_many :posts, dependent: :destroy
-  has_one :profile, dependent: :destroy
+  belongs_to :profile, polymorphic: true
 end
 ```
 
-### 2. Create Your Resource
+Define a resource class for each concrete type:
 
 ```ruby
-class UserResource < JPie::Resource
+# app/resources/user_resource.rb
+class UserResource < JSONAPI::Resource
   attributes :name, :email
-  meta_attributes :created_at, :updated_at
-  
-  has_many :posts
-  has_one :profile
+  has_one :profile  # auto-detected as polymorphic from model
 end
+
+# app/resources/admin_profile_resource.rb
+class AdminProfileResource < JSONAPI::Resource
+  attributes :department, :level
+end
+
+# app/resources/customer_profile_resource.rb
+class CustomerProfileResource < JSONAPI::Resource
+  attributes :company_name, :industry
+end
+```
+
+The gem auto-detects polymorphism from the model's association. To override, use `polymorphic: true` explicitly.
+
+Responses use the concrete type. For example, a user with an admin profile returns the concrete type in the relationship data and `included` array:
+
+```http
+GET /users/1?include=profile HTTP/1.1
+Accept: application/vnd.api+json
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "relationships": {
+      "profile": {
+        "data": { "type": "admin_profiles", "id": "5" }
+      }
+    }
+  },
+  "included": [
+    {
+      "type": "admin_profiles",
+      "id": "5",
+      "attributes": { "department": "Engineering", "level": "Senior" }
+    }
+  ]
+}
 ```
 
-### 3. Create Your Controller
+When creating or updating, provide the concrete type in the relationship payload:
+
+```http
+PATCH /users/1 HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
+
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "relationships": {
+      "profile": {
+        "data": { "type": "customer_profiles", "id": "10" }
+      }
+    }
+  }
+}
+```
+
+If you need direct access to polymorphic resources (e.g., `GET /admin_profiles/1`), add explicit routes:
 
 ```ruby
-class UsersController < ApplicationController
-  include JPie::Controller
+jsonapi_resources :admin_profiles
+jsonapi_resources :customer_profiles
+```
+
+## Single Table Inheritance (STI)
+
+STI subclasses are treated as first-class JSON:API resources with their own types. Use the `sti` option in routes:
+
+```ruby
+jsonapi_resources :notifications, sti: [:email_notifications, :sms_notifications]
+```
+
+This generates:
+
+- `GET /notifications` — lists all notifications (index only)
+- `GET /email_notifications/:id`, `POST /email_notifications`, etc. — full CRUD for each subtype
+- `GET /sms_notifications/:id`, `POST /sms_notifications`, etc.
+
+The models use standard Rails STI inheritance:
+
+```ruby
+class Notification < ActiveRecord::Base
+  validates :subject, presence: true
+end
+
+class EmailNotification < Notification
+  validates :recipient_email, presence: true
+end
+
+class SmsNotification < Notification
+  validates :phone_number, presence: true
 end
 ```
 
-### 4. Set Up Routes
+Subclass resources inherit attributes from the parent:
 
 ```ruby
-Rails.application.routes.draw do
-  resources :users
+class NotificationResource < JSONAPI::Resource
+  attributes :subject, :body
+end
+
+class EmailNotificationResource < NotificationResource
+  attributes :recipient_email  # inherits :subject, :body
+end
+
+class SmsNotificationResource < NotificationResource
+  attributes :phone_number  # inherits :subject, :body
 end
 ```
 
-That's it! You now have a fully functional JSON:API compliant server with automatic CRUD operations, sorting, includes, and validation.
+The base endpoint returns all subtypes with their concrete types:
+
+```http
+GET /notifications HTTP/1.1
+Accept: application/vnd.api+json
 
-## 📚 Comprehensive Examples
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
 
-JPie includes a complete set of examples demonstrating all features:
+{
+  "data": [
+    {
+      "type": "email_notifications",
+      "id": "1",
+      "attributes": {
+        "subject": "Welcome",
+        "body": "...",
+        "recipient_email": "user@example.com"
+      }
+    },
+    {
+      "type": "sms_notifications",
+      "id": "2",
+      "attributes": {
+        "subject": "Alert",
+        "body": "...",
+        "phone_number": "555-1234"
+      }
+    }
+  ]
+}
+```
 
-- **[🚀 Basic Usage](https://github.com/emilkampp/jpie/blob/main/examples/basic_usage.rb)** - Fundamental setup and configuration
-- **[🔗 Through Associations](https://github.com/emilkampp/jpie/blob/main/examples/through_associations.rb)** - Many-to-many relationships with `:through`
-- **[🎨 Custom Attributes & Meta](https://github.com/emilkampp/jpie/blob/main/examples/custom_attributes_and_meta.rb)** - Custom computed attributes and meta data
-- **[🔄 Polymorphic Associations](https://github.com/emilkampp/jpie/blob/main/examples/polymorphic_associations.rb)** - Complex polymorphic relationships
-- **[🏗️ Single Table Inheritance](https://github.com/emilkampp/jpie/blob/main/examples/single_table_inheritance.rb)** - STI models and resources
-- **[📊 Custom Sorting](https://github.com/emilkampp/jpie/blob/main/examples/custom_sorting.rb)** - Advanced sorting with complex algorithms
-- **[⚠️ Error Handling](https://github.com/emilkampp/jpie/blob/main/examples/error_handling.rb)** - Comprehensive error handling strategies
+To create or update, use the subtype endpoint with the concrete type:
 
-Each example is self-contained with models, resources, controllers, and sample API requests/responses. **[📋 View all examples →](https://github.com/emilkampp/jpie/blob/main/examples/)**
+```http
+POST /email_notifications HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
 
-## Generators
+{
+  "data": {
+    "type": "email_notifications",
+    "attributes": {
+      "subject": "Welcome",
+      "body": "Hello",
+      "recipient_email": "user@example.com"
+    }
+  }
+}
+```
 
-JPie includes a resource generator for quickly creating new resource classes:
+## Sorting
 
-### Basic Usage
+Sort collections with the `sort` parameter. Prefix with `-` for descending. Seperate multiple sorts with comma `,`:
 
-```bash
-# Generate a basic resource with semantic syntax
-rails generate jpie:resource User attribute:name attribute:email meta:created_at
+```http
+GET /users?sort=name,-created_at HTTP/1.1
+Accept: application/vnd.api+json
+```
 
-# Shorthand for relationships
-rails generate jpie:resource Post attribute:title attribute:content has_many:comments has_one:author
+Virtual attributes can also be sorted (loaded into memory first). Declare sort-only fields with `sortable_fields` to allow sorting without exposing the value:
 
-# Mix explicit categorization with auto-detection
-rails generate jpie:resource User attribute:name email created_at updated_at
+```ruby
+class User < ActiveRecord::Base
+  has_many :posts
+end
 ```
 
-**Generated file:**
 ```ruby
-class UserResource < JPie::Resource
+class UserResource < JSONAPI::Resource
   attributes :name, :email
-  meta_attributes :created_at, :updated_at
-  
-  has_many :comments
-  has_one :author
+  sortable_fields :posts_count
+
+  def posts_count
+    resource.posts.size
+  end
+end
+```
+
+## JSON:API Object
+
+All responses automatically include a `jsonapi` object indicating JSON:API version compliance:
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "data": { ... }
+}
+```
+
+The version is hardcoded to "1.1". You can add meta information to the jsonapi object via configuration:
+
+```ruby
+# config/initializers/json_api.rb
+JSONAPI.configure do |config|
+  config.jsonapi_meta = { ext: ["https://jsonapi.org/ext/atomic"] }
 end
 ```
 
-### Semantic Field Syntax
+## Meta Information
 
-| Syntax | Purpose | Example |
-|--------|---------|---------|
-| `attribute:field` | Regular JSON:API attribute | `attribute:name` |
-| `meta:field` | JSON:API meta attribute | `meta:created_at` |
-| `has_many:resource` | JSON:API relationship | `has_many:posts` |
-| `has_one:resource` | JSON:API relationship | `has_one:profile` |
+The gem supports meta information at three levels: document-level, resource-level, and relationship-level.
 
-### Generator Options
+### Document-Level Meta
 
-| Option | Description | Example |
-|--------|-------------|---------|
-| `--model=NAME` | Specify model class | `--model=Person` |
-| `--skip-model` | Skip explicit model declaration | `--skip-model` |
+Document-level meta appears at the top level of the response. Pagination automatically includes `total` when pagination is applied.
 
-### Modern DSL
+To add custom document-level meta globally, configure `document_meta_resolver`:
 
 ```ruby
-class UserResource < JPie::Resource
-  # Multiple attributes at once
-  attributes :name, :email, :created_at
-  
-  # Meta attributes (for additional data)
-  meta :account_status, :last_login
-  
-  # Relationships for includes
-  has_many :posts
-  has_one :profile
-  
-  # Custom sorting
-  sortable :popularity do |query, direction|
-    query.order(likes_count: direction)
+JSONAPI.configure do |config|
+  config.document_meta_resolver = lambda do |controller:|
+    {
+      request_id: controller.request.request_id,
+      api_version: "v1"
+    }
   end
-  
-  # Custom attribute methods (modern approach)
+end
+```
+
+The resolver receives the controller instance and returns a hash that is merged with pagination meta:
+
+```json
+{
+  "jsonapi": { "version": "1.1" },
+  "data": [...],
+  "meta": {
+    "request_id": "abc-123",
+    "api_version": "v1",
+    "total": 100
+  }
+}
+```
+
+For per-controller customization, override `jsonapi_document_meta` in a custom controller:
+
+```ruby
+class Api::UsersController < JSONAPI::ResourcesController
   private
-  
-  def account_status
-    object.active? ? 'active' : 'inactive'
+
+  def jsonapi_document_meta(extra_meta = {})
+    super(extra_meta.merge(custom_field: "value"))
+  end
+end
+```
+
+### Resource-Level Meta
+
+Resource-level meta appears within each resource object. By default, the gem automatically includes `created_at` and `updated_at` timestamps in ISO8601 format if the model responds to these methods.
+
+You can also define custom meta in two ways:
+
+**Class-level static meta:**
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :email, :name
+
+  meta({ version: "v1", custom: "value" })
+end
+```
+
+**Instance-level dynamic meta:**
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :email, :name
+
+  def meta
+    {
+      name_length: resource.name.length,
+      custom_field: "value"
+    }
+  end
+end
+```
+
+The instance method has access to the model instance via `resource`. Custom meta is merged with the default timestamp meta, with custom values taking precedence.
+
+**Example Resource-Level Meta:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "data": {
+    "type": "users",
+    "id": "1",
+    "attributes": {
+      "name": "John Doe",
+      "email": "john@example.com"
+    },
+    "meta": {
+      "created_at": "2024-01-15T10:30:00Z",
+      "updated_at": "2024-01-15T10:30:00Z",
+      "name_length": 8,
+      "custom_field": "value"
+    },
+    "links": {
+      "self": "/users/1"
+    }
+  }
+}
+```
+
+### Relationship-Level Meta
+
+Relationship-level meta appears within relationship objects:
+
+```ruby
+class UserResource < JSONAPI::Resource
+  attributes :email, :name
+
+  has_many :posts, meta: { count: 5, custom: "relationship_meta" }
+  has_one :profile, meta: { type: "polymorphic" }
+end
+```
+
+The response will include:
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "data": {
+    "type": "users",
+    "id": "1",
+    "attributes": {
+      "name": "John Doe",
+      "email": "john@example.com"
+    },
+    "relationships": {
+      "posts": {
+        "data": [
+          { "type": "posts", "id": "1" },
+          { "type": "posts", "id": "2" }
+        ],
+        "meta": {
+          "count": 5,
+          "custom": "relationship_meta"
+        }
+      },
+      "profile": {
+        "data": {
+          "type": "admin_profiles",
+          "id": "1"
+        },
+        "meta": {
+          "type": "polymorphic"
+        }
+      }
+    },
+    "links": {
+      "self": "/users/1"
+    }
+  }
+}
+```
+
+## Configuration
+
+Configure the gem in an initializer:
+
+```ruby
+# config/initializers/json_api.rb
+JSONAPI.configure do |config|
+  config.default_page_size = 25
+  config.max_page_size = 100
+  config.jsonapi_meta = nil
+  config.base_controller_class = ActionController::API  # Default: ActionController::API
+end
+```
+
+### Base Controller Class
+
+By default, `JSONAPI::BaseController` inherits from `ActionController::API`. You can configure it to inherit from a different base class (e.g., `ActionController::Base` or a custom base controller):
+
+```ruby
+JSONAPI.configure do |config|
+  # Use ActionController::Base instead of ActionController::API
+  config.base_controller_class = ActionController::Base
+
+  # Or use a custom base controller
+  config.base_controller_class = ApplicationController
+end
+```
+
+This is useful when you need access to features available in `ActionController::Base` that aren't in `ActionController::API`, such as:
+
+- View rendering helpers
+- Layout support
+- Cookie-based sessions
+- Flash messages
+
+**Note:** The configuration must be set before the gem's controllers are loaded. Set it in a Rails initializer that loads before `json_api` is required.
+
+## Authorization
+
+The gem provides two optional authorization hooks:
+
+- `authorization_scope` — filters collections (index) to authorized records
+- `authorization_handler` — authorizes individual actions (show, create, update, destroy)
+
+If not configured, authorization is bypassed.
+
+### Pundit Integration
+
+```ruby
+# config/initializers/json_api.rb
+JSONAPI.configure do |config|
+  config.authorization_scope = lambda do |controller:, scope:, action:, model_class:|
+    policy_class = Pundit::PolicyFinder.new(model_class).policy
+    policy_scope = policy_class.const_get(:Scope).new(controller.current_user, scope)
+    policy_scope.resolve
+  end
+
+  config.authorization_handler = lambda do |controller:, record:, action:, context: nil|
+    policy_class = Pundit::PolicyFinder.new(record).policy
+    policy = policy_class.new(controller.current_user, record)
+    unless policy.public_send("#{action}?")
+      raise JSONAPI::AuthorizationError, "Not authorized to #{action} this resource"
+    end
+  end
+end
+```
+
+The gem automatically renders `403 Forbidden` for `JSONAPI::AuthorizationError` and `Pundit::NotAuthorizedError`.
+
+Relationship endpoints authorize the parent resource with `action: :update` and `context: { relationship: :relationship_name }`.
+
+## Instrumentation (Rails 8.1+)
+
+When running on Rails 8.1 or later, the gem automatically emits structured events via `Rails.event` for all CRUD and relationship operations. This enables seamless integration with monitoring and APM platforms like Datadog, AppSignal, New Relic, or Honeycomb.
+
+### Resource Events
+
+The gem emits events for resource lifecycle operations:
+
+- **`jsonapi.{resource_type}.created`** - Emitted after successful resource creation
+- **`jsonapi.{resource_type}.updated`** - Emitted after successful resource updates (includes changed fields)
+- **`jsonapi.{resource_type}.deleted`** - Emitted after successful resource deletion
+
+**Event Payload Structure:**
+
+```ruby
+{
+  resource_type: "users",
+  resource_id: 123,
+  changes: { "name" => ["old", "new"], "phone" => ["old", "new"] }  # Only for updates
+}
+```
+
+**Example Usage:**
+
+```ruby
+# Subscribe to events
+class JsonApiEventSubscriber
+  def emit(event)
+    encoded = ActiveSupport::EventReporter.encoder(:json).encode(event)
+    # Forward to your monitoring service
+    MonitoringService.send_event(encoded)
+  end
+end
+
+Rails.event.subscribe(JsonApiEventSubscriber.new) if Rails.respond_to?(:event)
+```
+
+### Relationship Events
+
+The gem also emits events for relationship operations:
+
+- **`jsonapi.{resource_type}.relationship.updated`** - Emitted after successful relationship updates
+- **`jsonapi.{resource_type}.relationship.removed`** - Emitted after successful relationship removals
+
+**Event Payload Structure:**
+
+```ruby
+{
+  resource_type: "users",
+  resource_id: 123,
+  relationship_name: "posts",
+  related_type: "posts",      # Optional
+  related_ids: [456, 789]      # Optional
+}
+```
+
+### Testing Instrumentation
+
+Use Rails 8.1's `assert_events_reported` test helper to verify events are emitted:
+
+```ruby
+assert_events_reported([
+  { name: "jsonapi.users.created", payload: { resource_type: "users", resource_id: 123 } },
+  { name: "jsonapi.users.relationship.updated", payload: { relationship_name: "posts" } }
+]) do
+  post "/users", params: payload.to_json, headers: jsonapi_headers
+end
+```
+
+## Content Negotiation
+
+The gem enforces JSON:API content negotiation:
+
+- **Content-Type**: POST, PATCH, and PUT requests must include `Content-Type: application/vnd.api+json` header (returns `415 Unsupported Media Type` if missing)
+- **Accept**: If an `Accept` header is provided, it must include `application/vnd.api+json` or be `*/*` (returns `406 Not Acceptable` if explicitly set to non-JSON:API types)
+
+Blank or `*/*` Accept headers are allowed to support browser defaults.
+
+## Custom Controllers
+
+You can inherit from `JSONAPI::BaseController` to create custom controllers:
+
+```ruby
+class UsersController < JsonApi::BaseController
+  def index
+    # Custom implementation
   end
 end
 ```
 
-See the examples folder for more examples of how to use the DSL to solve various serialization/deserialization scenarios.
+The base controller provides helper methods:
+
+- `jsonapi_params` - Parsed JSON:API parameters
+- `jsonapi_attributes` - Extracted attributes
+- `jsonapi_relationships` - Extracted relationships
+- `parse_include_param` - Parsed include parameter
+- `parse_fields_param` - Parsed fields parameter
+- `parse_filter_param` - Parsed filter parameter
+- `parse_sort_param` - Parsed sort parameter
+- `parse_page_param` - Parsed page parameter
+
+## Serialization
+
+Use `JSONAPI::Serializer` to serialize resources:
+
+```ruby
+serializer = JSONAPI::Serializer.new(user)
+serializer.to_hash(include: ["posts"], fields: { users: ["name", "email"] })
+```
+
+## Deserialization
+
+Use `JSONAPI::Deserializer` to deserialize JSON:API payloads:
+
+```ruby
+deserializer = JSONAPI::Deserializer.new(params, resource_class: User)
+deserializer.attributes # => { "name" => "John", "email" => "john@example.com" }
+deserializer.relationship_ids(:posts) # => ["1", "2"]
+deserializer.to_params # => { "name" => "John", "post_ids" => ["1", "2"], "profile_id" => "1", "profile_type" => "CustomerProfile" }
+```
+
+The deserializer automatically converts JSON:API relationship format to Rails-friendly params:
+
+- To-many relationships: `posts` → `post_ids` (array)
+- To-one relationships: `account` → `account_id`
+- Polymorphic relationships: `profile` → `profile_id` and `profile_type`
+
+### Creating Resources with Relationships
+
+You can include relationships when creating resources:
+
+```http
+POST /users HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
+
+{
+  "data": {
+    "type": "users",
+    "attributes": {
+      "name": "John Doe",
+      "email": "john@example.com"
+    },
+    "relationships": {
+      "profile": {
+        "data": {
+          "type": "customer_profiles",
+          "id": "1"
+        }
+      },
+      "posts": {
+        "data": [
+          { "type": "posts", "id": "1" },
+          { "type": "posts", "id": "2" }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Updating Resources with Relationships
+
+You can update relationships when updating resources:
+
+```http
+PATCH /users/1 HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
+
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "attributes": {
+      "name": "John Doe Updated"
+    },
+    "relationships": {
+      "profile": {
+        "data": {
+          "type": "admin_profiles",
+          "id": "2"
+        }
+      },
+      "posts": {
+        "data": [
+          { "type": "posts", "id": "3" }
+        ]
+      }
+    }
+  }
+}
+```
+
+### Clearing Relationships
+
+To clear a relationship, send `null` for to-one relationships or an empty array for to-many relationships:
+
+```http
+PATCH /users/1 HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
+
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "relationships": {
+      "profile": {
+        "data": null
+      }
+    }
+  }
+}
+```
+
+```http
+PATCH /users/1 HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
+
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "relationships": {
+      "posts": {
+        "data": []
+      }
+    }
+  }
+}
+```
+
+### Relationship Validation
+
+The gem validates relationship data:
+
+- Missing `type` or `id` in relationship data returns `400 Bad Request`
+- Invalid relationship type (for non-polymorphic associations) returns `400 Bad Request`
+- Invalid polymorphic type (class doesn't exist) returns `400 Bad Request`
+- Attempting to unset linkage that cannot be nullified (e.g., foreign key has NOT NULL constraint) returns `400 Bad Request`
+
+## Relationship Endpoint Details
+
+The gem provides dedicated endpoints for managing relationships independently of the main resource:
+
+### Show Relationship
+
+```http
+GET /users/1/relationships/posts HTTP/1.1
+Accept: application/vnd.api+json
+```
+
+Returns the relationship data (resource identifiers) with links and meta:
+
+**To-Many Relationship Response:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "data": [
+    { "type": "posts", "id": "1" },
+    { "type": "posts", "id": "2" }
+  ],
+  "links": {
+    "self": "/users/1/relationships/posts",
+    "related": "/users/1/posts"
+  },
+  "meta": {
+    "count": 2
+  }
+}
+```
+
+**To-One Relationship Response:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "data": {
+    "type": "admin_profiles",
+    "id": "1"
+  },
+  "links": {
+    "self": "/users/1/relationships/profile",
+    "related": "/users/1/profile"
+  }
+}
+```
+
+**Empty To-One Relationship Response:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "data": null,
+  "links": {
+    "self": "/users/1/relationships/profile",
+    "related": "/users/1/profile"
+  }
+}
+```
+
+For collection relationships, you can sort using the `sort` parameter:
+
+```http
+GET /users/1/relationships/posts?sort=title,-created_at HTTP/1.1
+Accept: application/vnd.api+json
+```
+
+### Update Relationship
+
+```http
+PATCH /users/1/relationships/posts HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
+
+{
+  "data": [
+    { "type": "posts", "id": "3" },
+    { "type": "posts", "id": "4" }
+  ]
+}
+```
+
+Replaces the entire relationship linkage. For to-one relationships, send a single resource identifier object (or `null` to clear). For to-many relationships, send an array of resource identifiers (or empty array `[]` to clear).
+
+### Delete Relationship Linkage
+
+```http
+DELETE /users/1/relationships/posts HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
+
+{
+  "data": [
+    { "type": "posts", "id": "1" }
+  ]
+}
+```
+
+Removes specific resources from a to-many relationship by setting their foreign key to `NULL`. For to-one relationships, send a single resource identifier object to remove the linkage.
+
+**Important**: Per JSON:API specification, relationship endpoints (`DELETE /users/:id/relationships/posts`) only modify linkage and never destroy resources. The gem attempts to unset the linkage by setting the foreign key to `NULL`. If this operation fails (due to NOT NULL constraints, validations, or other database constraints), a `400 Bad Request` error is returned. To allow relationship removal, ensure the foreign key column allows `NULL` values and any validations permit nullification.
+
+Error responses follow JSON:API error format:
+
+**Example Error Response:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "errors": [
+    {
+      "status": "400",
+      "title": "Invalid Relationship",
+      "detail": "Invalid relationship type for profile: 'invalid_type' does not correspond to a valid model class",
+      "source": {
+        "pointer": "/data/relationships/profile/data/type"
+      }
+    }
+  ]
+}
+```
+
+**Example 404 Not Found Error:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "errors": [
+    {
+      "status": "404",
+      "title": "Record Not Found",
+      "detail": "Couldn't find User with 'id'=999"
+    }
+  ]
+}
+```
+
+**Example Validation Error:**
+
+```json
+{
+  "jsonapi": {
+    "version": "1.1"
+  },
+  "errors": [
+    {
+      "status": "422",
+      "title": "Validation Error",
+      "detail": "Email can't be blank",
+      "source": {
+        "pointer": "/data/attributes/email"
+      }
+    },
+    {
+      "status": "422",
+      "title": "Validation Error",
+      "detail": "Name is too short (minimum is 2 characters)",
+      "source": {
+        "pointer": "/data/attributes/name"
+      }
+    }
+  ]
+}
+```
+
+## ActiveStorage Support
+
+The gem automatically detects and serializes ActiveStorage attachments when exposed as relationships.
+
+### Exposing Attachments
+
+Declare ActiveStorage attachments as relationships in your resource:
+
+```ruby
+class User < ApplicationRecord
+  has_one_attached :avatar
+  has_many_attached :documents
+end
+
+class UserResource < JSONAPI::Resource
+  attributes :name, :email
+  has_one :avatar
+  has_many :documents
+end
+```
+
+The gem auto-detects these are ActiveStorage attachments and serializes them as `active_storage_blobs` relationships:
+
+```http
+GET /users/1?include=avatar HTTP/1.1
+Accept: application/vnd.api+json
+
+HTTP/1.1 200 OK
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "attributes": { "name": "John Doe", "email": "john@example.com" },
+    "relationships": {
+      "avatar": { "data": { "type": "active_storage_blobs", "id": "1" } },
+      "documents": { "data": [
+        { "type": "active_storage_blobs", "id": "2" },
+        { "type": "active_storage_blobs", "id": "3" }
+      ]}
+    }
+  },
+  "included": [{
+    "type": "active_storage_blobs",
+    "id": "1",
+    "attributes": {
+      "filename": "avatar.jpg",
+      "content_type": "image/jpeg",
+      "byte_size": 102400,
+      "checksum": "abc123...",
+      "url": "/rails/active_storage/blobs/.../avatar.jpg"
+    },
+    "links": {
+      "self": "/active_storage_blobs/1",
+      "download": "/rails/active_storage/blobs/.../avatar.jpg"
+    }
+  }]
+}
+```
+
+The built-in `JSONAPI::ActiveStorageBlobResource` provides `filename`, `content_type`, `byte_size`, `checksum`, and `url` attributes, plus a download link.
+
+### Attaching Files
+
+Clients attach files by providing signed blob IDs from ActiveStorage direct uploads:
+
+```http
+POST /users HTTP/1.1
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "type": "users",
+    "attributes": { "name": "Jane Doe", "email": "jane@example.com" },
+    "relationships": {
+      "avatar": { "data": { "type": "active_storage_blobs", "id": "eyJfcmFpbHMi..." } },
+      "documents": { "data": [
+        { "type": "active_storage_blobs", "id": "signed-id-1" },
+        { "type": "active_storage_blobs", "id": "signed-id-2" }
+      ]}
+    }
+  }
+}
+```
+
+The deserializer validates signed IDs via `ActiveStorage::Blob.find_signed!` and converts them to blob objects for attachment. Invalid signed IDs raise `ActiveSupport::MessageVerifier::InvalidSignature`.
+
+### Detaching Files
+
+Send `null` or `[]` to detach attachments:
+
+```http
+PATCH /users/1 HTTP/1.1
+Content-Type: application/vnd.api+json
+
+{
+  "data": {
+    "type": "users",
+    "id": "1",
+    "relationships": {
+      "avatar": { "data": null },
+      "documents": { "data": [] }
+    }
+  }
+}
+```
+
+By default, this purges the attachments. For has_one, sending `null` detaches. For has_many, sending `[]` removes all.
+
+### Relationship Options
+
+**`purge_on_nil`** (default: `true`) — Controls whether attachments are purged when set to `null`/`[]`:
+
+```ruby
+has_one :avatar, purge_on_nil: false   # Keep existing when null
+has_many :documents, purge_on_nil: false
+```
+
+**`append_only`** (has_many only, default: `false`) — Append new blobs instead of replacing:
+
+```ruby
+has_many :documents, append_only: true
+```
+
+When enabled:
+
+- New blobs append to existing: `[blob1, blob2] + [blob3] → [blob1, blob2, blob3]`
+- Empty array `[]` is a no-op (preserves existing)
+- Implicitly sets `purge_on_nil: false`
+- Remove attachments via the DELETE relationship endpoint
+
+These options are mutually exclusive — `append_only: true` with `purge_on_nil: true` raises `ArgumentError`.
+
+## Client Integration: devour-client-ts
+
+The `devour-client-ts` npm package is a TypeScript JSON:API client that works seamlessly with this gem. This section covers how to configure and use devour-client-ts as a frontend client.
+
+### Installation
+
+```bash
+npm install devour-client-ts
+```
+
+### Basic Client Setup
+
+```typescript
+import { JsonApi } from "devour-client-ts";
+
+const api = new JsonApi({
+  apiUrl: "http://localhost:3000",
+  headers: {
+    "Content-Type": "application/vnd.api+json",
+    Accept: "application/vnd.api+json",
+  },
+  trailingSlash: false, // Rails doesn't use trailing slashes
+  resetBuilderOnCall: true, // Prevent state pollution between calls
+});
+```
+
+### Defining Models
+
+Define models that match your Rails resources. Model names are singular, but `collectionPath` should be plural to match JSON:API conventions:
+
+```typescript
+// Simple model
+api.define(
+  "user",
+  {
+    email: {},
+    name: {},
+    phone: {},
+  },
+  {
+    collectionPath: "users",
+  }
+);
+
+// Model with relationships
+api.define(
+  "post",
+  {
+    title: {},
+    body: {},
+    user: {
+      jsonApi: "hasOne",
+      type: "users", // Must be plural
+    },
+    comments: {
+      jsonApi: "hasMany",
+      type: "comments", // Must be plural
+    },
+  },
+  {
+    collectionPath: "posts",
+  }
+);
+```
+
+**Important**: All relationship `type` values must be **plural** to match JSON:API specification. Using singular types (e.g., `type: 'user'`) will cause "Type Mismatch" errors.
+
+### CRUD Operations
+
+**Find all resources:**
+
+```typescript
+const { data: users } = await api.findAll("user").toPromise();
+```
+
+**Find a single resource:**
+
+```typescript
+const { data: user } = await api.find("user", "123").toPromise();
+```
+
+**Find with relationships:**
+
+```typescript
+const { data: user } = await api
+  .find("user", "123", {
+    include: ["posts", "profile"],
+  })
+  .toPromise();
+
+// Relationships are deserialized onto the resource
+console.log(user.posts); // Array of post objects
+console.log(user.profile); // Profile object
+```
+
+**Create a resource:**
+
+```typescript
+const { data: newUser } = await api
+  .create("user", {
+    name: "John Doe",
+    email: "john@example.com",
+  })
+  .toPromise();
+```
+
+**Create with relationships:**
+
+```typescript
+const { data: newPost } = await api
+  .create("post", {
+    title: "My Post",
+    body: "Content here",
+    user: { id: "123", type: "users" }, // hasOne - single object
+  })
+  .toPromise();
+```
+
+**Update a resource:**
+
+```typescript
+const { data: updated } = await api
+  .update("user", {
+    id: "123",
+    name: "Updated Name",
+  })
+  .toPromise();
+```
+
+**Delete a resource:**
+
+```typescript
+await api.destroy("user", "123").toPromise();
+```
+
+### Query Parameters
+
+**Filtering:**
+
+```typescript
+const { data: users } = await api
+  .findAll("user", {
+    filter: {
+      name_eq: "John",
+      created_at_gte: "2024-01-01",
+    },
+  })
+  .toPromise();
+```
+
+**Sorting:**
+
+```typescript
+const { data: users } = await api
+  .findAll("user", {
+    sort: "name", // Single field ascending
+  })
+  .toPromise();
+
+const { data: users } = await api
+  .findAll("user", {
+    sort: "-created_at", // Descending (prefix with -)
+  })
+  .toPromise();
+
+const { data: users } = await api
+  .findAll("user", {
+    sort: ["name", "-created_at"], // Multiple fields
+  })
+  .toPromise();
+```
+
+**Pagination:**
+
+```typescript
+const { data: users, meta } = await api
+  .findAll("user", {
+    page: {
+      number: 1,
+      size: 10,
+    },
+  })
+  .toPromise();
+
+console.log(meta.total); // Total count
+```
+
+**Sparse fieldsets:**
+
+```typescript
+const { data: users } = await api
+  .findAll("user", {
+    fields: {
+      users: ["name", "email"],
+      posts: ["title"],
+    },
+  })
+  .toPromise();
+```
+
+**Including related resources:**
+
+```typescript
+const { data: user } = await api
+  .find("user", "123", {
+    include: ["posts", "posts.comments"],
+  })
+  .toPromise();
+```
+
+### Relationship Operations
+
+**Update a relationship:**
+
+```typescript
+await api
+  .one("user", "123")
+  .relationships("posts")
+  .patch([
+    { id: "1", type: "posts" },
+    { id: "2", type: "posts" },
+  ])
+  .toPromise();
+```
+
+### Authentication Middleware
+
+Add authentication middleware to automatically inject tokens:
+
+```typescript
+const authMiddleware = {
+  name: "auth",
+  req: (payload) => {
+    const token = localStorage.getItem("auth_token");
+    if (token) {
+      payload.req.headers = {
+        ...payload.req.headers,
+        Authorization: `Bearer ${token}`,
+      };
+    }
+    return payload;
+  },
+  error: (payload) => {
+    if (payload.res?.status === 401) {
+      localStorage.removeItem("auth_token");
+      // Redirect to login
+    }
+    throw payload;
+  },
+};
+
+api.replaceMiddleware("add-bearer-token", authMiddleware);
+```
+
+### Polymorphic Relationships
+
+For polymorphic relationships, omit the `type` in the model definition and provide it when creating/updating:
+
+```typescript
+// Model definition - no type constraint
+api.define(
+  "workstream",
+  {
+    topic: {},
+    subject: {
+      jsonApi: "hasOne",
+      // No type - polymorphic
+    },
+  },
+  {
+    collectionPath: "workstreams",
+  }
+);
+
+// Create with polymorphic relationship
+const { data: workstream } = await api
+  .create("workstream", {
+    topic: "edit",
+    subject: { id: "456", type: "vendors" }, // Provide type at runtime
+  })
+  .toPromise();
+```
+
+### Error Handling
+
+```typescript
+try {
+  const { data: user } = await api.find("user", "123").toPromise();
+} catch (error) {
+  if (error.response?.status === 401) {
+    // Authentication error
+  } else if (error.response?.status === 422) {
+    // Validation errors
+    const errors = error.response.data.errors;
+    errors.forEach((err) => {
+      console.error(`${err.source?.pointer}: ${err.detail}`);
+    });
+  } else if (error.response?.status === 400) {
+    // Bad request (invalid filters, sort fields, etc.)
+    console.error(error.response.data.errors);
+  }
+}
+```
+
+### Key Integration Points
+
+| Rails (json_api gem)           | devour-client-ts                                   |
+| ------------------------------ | -------------------------------------------------- |
+| `attributes :name, :email`     | `{ name: {}, email: {} }`                          |
+| `has_many :posts`              | `posts: { jsonApi: 'hasMany', type: 'posts' }`     |
+| `has_one :profile`             | `profile: { jsonApi: 'hasOne', type: 'profiles' }` |
+| `filters :name_eq`             | `filter: { name_eq: 'value' }`                     |
+| `sort=name,-date`              | `sort: ['name', '-date']`                          |
+| `include=posts.comments`       | `include: ['posts', 'posts.comments']`             |
+| `page[number]=1&page[size]=10` | `page: { number: 1, size: 10 }`                    |
+| `fields[users]=name,email`     | `fields: { users: ['name', 'email'] }`             |
+
+### Common Gotchas
+
+1. **Plural types required**: All `type` values in relationships must be plural (`users`, not `user`)
+2. **Relationship assignment**: Assign relationships directly on the resource (`user: { id, type }`), not in a `relationships` wrapper
+3. **Content-Type header**: Must be `application/vnd.api+json` for POST/PATCH/PUT requests
+4. **Filter values**: Comma-separated filter values are parsed as a single string; use array notation for multiple values
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/emilkampp/jpie.
+Bug reports and pull requests are welcome on GitHub at https://github.com/klaay/json_api.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).