Getting started with AshJsonApi

mix igniter.install ash_json_api

This manual setup branches off from the Getting Started with Ash guide. If you aren't starting from there, replace the application name, Helpdesk, with your application name, and replace the Ash.Domain name, Helpdesk.Support with a domain or domains from your own application.

Add the ash_json_api dependency

In your mix.exs, add the Ash JSON API dependency:

  defp deps do
    [
      # .. other dependencies
      {:ash_json_api, "~> 1.0"},
    ]
  end

Accept json_api content type

Add the following to your config/config.exs.

# config/config.exs
config :mime,
  extensions: %{"json" => "application/vnd.api+json"},
  types: %{"application/vnd.api+json" => ["json"]}

This configuration is required to support working with the JSON:API custom mime type.

After adding the configuration above, compiling the project might throw an error:

ERROR! the application :mime has a different value set for key :types during runtime compared to compile time.

This can happen if :mime was already compiled before the configuration was changed and can be fixed by running

mix deps.compile mime --force

Create a router

Create a separate Router Module to work with your Domains. It will generate the routes for your Resources and provide the functions you would usually have in a Controller.

We will later forward requests from your Applications primary (Phoenix) Router to you Ash JSON API Router.

defmodule HelpdeskWeb.JsonApiRouter do
  use AshJsonApi.Router,
    # The api modules you want to serve
    domains: [Helpdesk.Support],
    # optionally an open_api route
    open_api: "/open_api"
end

Additionally, your Resource requires a type, a base route and a set of allowed HTTP methods and what action they will trigger.

Add AshJsonApi.Plug.Parser to your endpoint

This handles any file uploads, if you have resource actions with the :file type.

plug Plug.Parsers,
  parsers: [:urlencoded, :multipart, :json, AshJsonApi.Plug.Parser], # <- add it to this list.
  pass: ["*/*"],
  json_decoder: Jason

You don't have to add this if you don't plan on doing any file uploads, but there is no cost to adding it, even if you don't use it.

Add the routes from your domain module(s)

To make your Resources accessible to the outside world, forward requests from your Phoenix router to the router you created for your domains.

For example:

scope "/api/json" do
  pipe_through(:api)

  forward "/helpdesk", HelpdeskWeb.JsonApiRouter
end

To set up an existing resource of your own with AshJsonApi, run:

mix ash.patch.extend Your.Resource.Name json_api

Add to your domain:

defmodule Helpdesk.Support do
  use Ash.Domain, extensions: [AshJsonApi.Domain]
  ...

And to your resource:

defmodule Helpdesk.Support.Ticket do
  use Ash.Resource, extensions: [AshJsonApi.Resource]
  # ...
  json_api do
    type "ticket"
  end
end