A Resource is simply a module that describes how to render your data as JSON:API resources.

You can implement a resource by "use-ing" the JSONAPIPlug.Resource module, which is recommeded, or by adopting the JSONAPIPlug.Resource behaviour and implementing all of the callback functions:

defmodule MyApp.UsersResource do
  use JSONAPIPlug.Resource,
    type: "user",
    attributes: [:name, :surname, :username]
end

See options/0 for all available options you can pass to use JSONAPIPlug.Resource.

You can now call UsersResource.render("show.json", %{data: user}) or Resource.render(UsersResource, conn, user) to render a valid JSON:API document from your data. If you use phoenix, you can use:

render(conn, "show.json", %{data: user})

in your controller functions to render the document in the same way.

Attributes

By default, the resulting JSON document consists of resources taken from your data. Only resource attributes defined on the resource will be (de)serialized. You can customize how attributes are handled by passing a keyword list of options:

defmodule MyApp.UsersResource do
  use JSONAPIPlug.Resource,
    type: "user",
    attributes: [
      username: nil,
      fullname: [deserialize: false, serialize: &fullname/2]
    ]

  defp fullname(resource, conn), do: "#{resouce.first_name} #{resource.last_name}"
end

In this example we are defining a computed attribute by passing the serialize option a function reference. Serialization functions take resource and conn as arguments and return the attribute value to be serialized. The deserialize option set to false makes sure the attribute is not deserialized when receiving a request.

Relationships

Relationships are defined by passing the relationships option to use JSONAPIPlug.Resource.

defmodule MyApp.PostResource do
  use JSONAPIPlug.Resource,
    type: "post",
    attributes: [:text, :body]
    relationships: [
      author: [resource: MyApp.UsersResource],
      comments: [many: true, resource: MyApp.CommentsResource]
    ]
end

defmodule MyApp.CommentsResource do
  alias MyApp.UsersResource

  use JSONAPIPlug.Resource,
    type: "comment",
    attributes: [:text]
    relationships: [post: [resource: MyApp.PostResource]]
end

When requesting GET /posts?include=author, if the author key is present on the data you pass from the controller it will appear in the included section of the JSON:API response.

Links

When rendering resource links, the default behaviour is to is to derive values for host, port and scheme from the connection. If you need to use different values for some reason, you can override them using JSONAPIPlug.API configuration options in your api configuration:

config :my_app, MyApp.API, host: "adifferenthost.com"