Resty v0.12.0 Resty.Resource.Base View Source

This module is used to create resource struct that you’ll then be able to use with Resty.Repo and Resty.Resource.

Using the module

Resty.Resource.Base is here to help you create resource structs. The resource struct and its module holds informations about how to query the API such as the site, headers, path, auth etc…

This module (Resty.Resource.Base) defines a lot of macros to configure these options. You’ll be able to call them right after calling use Resty.Resource.Base.

defmodule MyResource do
  use Resty.Resource.Base

  set_site "site.tld"
  set_resource_path "/posts"

  define_attributes [:name]
end

Primary key

By default resty resources have a primary key attriubute that defaults to :id. If you want to use another field as the primary key you can set it thanks to the set_primary_key/1 macro.

Attributes

Unlike ActiveResource Resty will need you to define which attributes should be allowed on the resource.

They are defined thanks to the define_attributes/1 macro. The attributes does not support type casting, types are taken as they come from the configured Resty.Serializer.

Using the resource

Once you have a resource you can use it with Resty.Repo and Resty.Resource in order to query the API or get informations about retrieved resources.

MyResource |> Resty.Repo.all!()

Link to this section Summary

Functions

Add an header to the request sent from this resource

Define the given attributes on the resource struct

Include the given root when serializing the resource

Set the Resty.Connection implementation that should be used to query this resource

Sets the resource extension. The extension will be added in the URL

This will replace the default headers (Resty.default_headers/0) used by this resource

Sets the resource primary key. By default it is :id

Add a path to the resource

Set the Resty.Serializer implementation that should be used to serialize and deserialize this resource

Add a site to the resource

Set the Resty.Auth implementation that should be used to query this resource

Link to this section Functions

Link to this macro add_header(name, value) View Source (macro)

Add an header to the request sent from this resource

Link to this macro belongs_to(resource, attribute_name, foreign_key, eager_load \\ true) View Source (macro)

Declare a new belongs_to association.

Arguments

  • resource: The resource module to which this association should resolve
  • attribute_name: Under which key should the resolved association be set?
  • foreign_key: What is the foreign_key of the association (in this resource)?
  • eager_load: Should this association be eagerly loaded? this parameter is useful in order to break circular dependencies or if you plan on using collection functions such as Resty.Repo.all/1.

Usage

defmodule User do
  use Resty.Resource.Base

  set_site "https://jsonplaceholder.typicode.com"
  set_resource_path "/users"
  define_attributes [:name, :email]
end

defmodule Post do
  use Resty.Resource.Base

  set_site "https://jsonplaceholder.typicode.com"
  set_resource_path "/posts"
  define_attributes [:title, :body, :userId]

  belongs_to User, :user, :userId
end

{:ok, post} = Post |> Resty.Repo.find(1)

IO.inspect(post.user) # %User{id: 1, email: "Sincere@april.biz", name: "Leanne Graham"}

When is the association loaded?

The belongs to association is automatically loaded when the resource is fetched from the server.

Beware! This is highly ineficient if you are using the Resty.Repo.all/1 function (or any other function that relies on it).

Link to this macro define_attributes(attributes) View Source (macro)

Define the given attributes on the resource struct.

Link to this macro has_one(resource, attribute_name, foreign_key, eager_load \\ true) View Source (macro)

Declare a new has_one association.

Arguments

  • resource: The resource module to which this association should resolve
  • attribute_name: Under which key should the resolved association be set?
  • foreign_key: What is the foreign_key of the association (on the other resource)? it should be :author_id if the resource url is (/authors/:author_id/address)
  • eager_load: Should this association be eagerly loaded? this parameter is useful in order to break circular dependencies or if you plan on using collection functions such as Resty.Repo.all/1.

Usage

defmodule Company do
  use Resty.Resource.Base

  set_site "https://jsonplaceholder.typicode.com"
  set_resource_path "/users/:user_id/company"
  define_attributes [:name]
end

defmodule User do
  use Resty.Resource.Base

  set_site "https://jsonplaceholder.typicode.com"
  set_resource_path "/users"
  define_attributes [:name, :email]

  has_one Company, :company, :user_id
end

{:ok, user} = User |> Resty.Repo.find(1)

IO.inspect(user.company.name) # Romaguera-Crona

When is the association loaded?

The has_one association is automatically loaded when the resource is fetched from the server.

Beware! This is highly ineficient if you are using the Resty.Repo.all/1 function (or any other function that relies on it).

Link to this macro include_root(value) View Source (macro)

Include the given root when serializing the resource

Link to this macro set_connection(connection, params \\ []) View Source (macro)

Set the Resty.Connection implementation that should be used to query this resource.

Link to this macro set_extension(extension) View Source (macro)

Sets the resource extension. The extension will be added in the URL.

Link to this macro set_headers(new_headers) View Source (macro)

This will replace the default headers (Resty.default_headers/0) used by this resource.

Link to this macro set_primary_key(name) View Source (macro)

Sets the resource primary key. By default it is :id.

Link to this macro set_resource_path(path) View Source (macro)

Add a path to the resource

Link to this macro set_serializer(serializer, params \\ []) View Source (macro)

Set the Resty.Serializer implementation that should be used to serialize and deserialize this resource.

Link to this macro set_site(site) View Source (macro)

Add a site to the resource

Link to this macro with_auth(auth, params \\ []) View Source (macro)

Set the Resty.Auth implementation that should be used to query this resource.