AshJsonApi Guidelines

AshJsonApi generates JSON:API compliant endpoints from Ash resources, supporting filtering, sorting, pagination, includes, and relationships.

Domain Configuration

Add the AshJsonApi.Domain extension and define routes:

defmodule MyApp.Blog do
  use Ash.Domain,
    extensions: [AshJsonApi.Domain]

  json_api do
    authorize? true

    routes do
      base_route "/posts", MyApp.Blog.Post do
        get :read
        index :read
        post :create
        patch :update
        delete :destroy
      end
    end
  end

  resources do
    resource MyApp.Blog.Post
    resource MyApp.Blog.Comment
  end
end

Resource Configuration

Add the AshJsonApi.Resource extension and specify the type:

defmodule MyApp.Blog.Post do
  use Ash.Resource,
    domain: MyApp.Blog,
    extensions: [AshJsonApi.Resource]

  attributes do
    uuid_primary_key :id
    attribute :title, :string
    attribute :body, :string
    attribute :published, :boolean
  end

  relationships do
    belongs_to :author, MyApp.Accounts.User
    has_many :comments, MyApp.Blog.Comment
  end

  json_api do
    type "post"  # Required: JSON:API type name
  end

  actions do
    defaults [:create, :read, :update, :destroy]

    read :list_published do
      filter expr(published == true)
    end

    update :publish do
      accept []
      change set_attribute(:published, true)
    end
  end
end

Route Types

Query Parameters

Standard JSON:API query parameters:

# Filter
?filter[attribute]=value

# Sort (descending with -)
?sort=attribute,-other_attribute

# Pagination
?page[number]=2&page[size]=10

# Includes (sideload related resources)
?include=author,comments.author