You can use any struct as a resource by deriving or directly implementing the JSONAPIPlug.Resource protocol:

defmodule MyApp.User do
  @derive {
    JSONAPIPlug.Resource,
    type: "user",
    attributes: [:name, :surname, :username]
  }
  defstruct id: nil, name: nil, surname: nil, username: nil
end

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

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.User do
  @derive {
    JSONAPIPlug.Resource,
    type: "user",
    attributes: [
      username: nil,
      fullname: [deserialize: false]
    ]
  }
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.Post do
  @derive {
    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

  @derive {
    JSONAPIPlug.Resource,
    type: "comment",
    attributes: [:text]
    relationships: [post: [resource: MyApp.Post]]
  }
  defstruct text: nil, post: nil
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"