JsonApiClient Ruby Client

By default, JsonApiClient::Resource.find(id) returns an array. If id is blank (nil or empty string), the client attempts to call the INDEX endpoint (e.g., /users/) instead of the SHOW endpoint. This can result in silently returning the first available resource from the index. To ensure a JsonApiClient::Errors::NotFound is raised instead, set raise_on_blank_find_param = true in your base resource class.

class Resource < JsonApiClient::Resource
  self.raise_on_blank_find_param = true
end

You can replace the default connection with a custom class that implements a run method. The default connection uses Faraday, allowing you to inject middleware (like OAuth2 or loggers) via the connection block. It is recommended to configure this in a base model that all resources inherit from.

# Define a custom connection class
class NullConnection
  def initialize(*args); end
  def run(request_method, path, params: nil, headers: {}, body: nil); end
  def use(*args); end
end

# Assign it to a resource
class CustomConnectionResource < TestResource
  self.connection_class = NullConnection
end

# Configure middleware in the base class
MyApi::Base.connection do |connection|
  connection.use FaradayMiddleware::OAuth2, 'MYTOKEN'
  connection.use Faraday::Response::Logger
  connection.use MyCustomMiddleware
end

To use json_api_client, create resource classes that inherit from JsonApiClient::Resource. It is recommended to create an abstract base class to set the API base URL (self.site) and share common behavior across your models. You can namespace your models; namespacing does not affect the URL routing.

By convention, the library guesses the resource route from the class name (e.g., Article maps to /articles, Person maps to /people).

module MyApi
  # Abstract base class
  class Base < JsonApiClient::Resource
    self.site = "http://example.com/"
  end

  class Article < Base
  end

  class Comment < Base
  end

  class Person < Base
  end
end

A resource can be marked as immutable using the immutable class method. This is useful for resources that should only be read from the API and never modified or deleted by the client.

When a resource is immutable:

1. save and destroy will raise JsonApiClient::Errors::ResourceImmutableError.
2. custom_endpoint definitions are restricted to the :get request method.

class Configuration < JsonApiClient::Resource
  immutable true
end

config = Configuration.find(1)
config.update(setting: 'new') # Raises JsonApiClient::Errors::ResourceImmutableError

You can specify an HTTP proxy for your connection using the connection_options hash on your resource or base class.

MyApi::Base.connection_options[:proxy] = 'http://proxy.example.com'

MyApi::Base.connection do |connection|
  # ...
end

Once a schema is defined, you can use the Property objects within it to cast raw input values into their intended Ruby types. When Property#cast(value) is called:

1. If the value is nil, it returns nil.
2. If no type is defined for the property, it returns the value as-is.
3. If a type is defined, it looks up the corresponding caster in the TypeFactory.
4. If a caster is found, it calls caster.cast(value, default).
5. If no caster is found for the specified type, it returns the value as-is.

schema = JsonApiClient::Schema.new
schema.add :count, type: :integer, default: 0

# Accessing a property and casting
property = schema.find(:count)

property.cast("42") # => 42 (Integer)
property.cast(nil)   # => nil

The JsonApiClient::Helpers::Dirty module provides mechanisms to track which attributes on a resource instance have been modified. It allows you to detect changes, retrieve the previous values of changed attributes, and manage the state of these changes. This is useful when you need to perform partial updates or audit changes before sending them to a JSON:API server.

Key capabilities include:

• Checking if any attributes have changed using changed?.
• Retrieving a list of changed attribute names via changed.
• Accessing the original value of a changed attribute using attribute_was(attr) or dynamic attr_was methods.
• Manually marking an attribute as changed using attribute_will_change!(attr).
• Clearing all tracked changes with clear_changes_information.

The params method aggregates all query components into a single hash used for the outgoing request. The order of precedence (later merges overwrite earlier ones) is:

1. filter_params (from where)
2. pagination_params (from page/per)
3. includes_params (from includes)
4. order_params (from order)
5. select_params (from select)
6. primary_key_params (from find or primary_key option)
7. path_params (from where or initialization)
8. additional_params (from with_params)

This ensures that specific identifiers and path parameters take precedence over general filters.