Skip to content
A provider for REST API Builder that uses Ecto Schema Store to provide resources.
Elixir
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config
lib/rest_api_builder
test
.gitignore
CHANGELOG.md
LICENSE.md
README.md
mix.exs
mix.lock

README.md

REST API Builder - Ecto Schema Store Provider

An API resource provider for the rest_api_builder project. This provider allows a developer to back a rest service using a store provided by this library.

REST API Builder

This works is still early access may be changed significantly as that the rest_api_builder library is still under initial development.

This documentation will focus on the provider itself. To see more documentation for rest_api_builder please visit that project in Hex.

Installation

def deps do
  [{:rest_api_builder_essp, "~> 0.6"}]
end

Using

defmodule Customer do
  use EctoTest.Web, :model

  schema "customers" do
    field :name, :string
    field :email, :string
    field :account_closed, :boolean, default: false

    timestamps
  end

  def changeset(model, params) do
    model
    |> cast(params, [:name, :email])
  end
end

defmodule CustomerStore do
  use EctoSchemaStore, schema: Customer, repo: MyApp.Repo
end

defmodule CustomersApi do
  use RestApiBuilder, plural_name: :customers, singular_name: :customer, activate: :all

  provider RestApiBuilder.EctoSchemaStoreProvider, store: CustomerStore
end

Configuring the provider

  • store - The module that implements the store interface.
  • parent_field - The field name of the parent schema id in the Ecto schema definition. This is used when a REST API module is a child to another.
  • soft_delete - By default the provider will delete the record. This takes a tuple of {field_name, value_to_set}. When set, will update the record and exclude it from future query results.
  • include - Which fields to include in the resource. By default only, non-association fields are included.
  • exclude - Which fields that woudl normally be included need to be excluded from the resource output.
  • preload - List of associations to preload when querying records. Dependent on need, child associations may be better as their own REST API module.

In addition, the provider also adds a command to the REST API module that allows the developer to set which changesets to use when creating or updating by default.

defmodule CustomersApi do
  use RestApiBuilder, plural_name: :customers, singular_name: :customer, activate: :all

   provider RestApiBuilder.EctoSchemaStoreProvider, store: CustomerStore,
                                                    soft_delete: {:account_closed, true},
                                                    exclude: [:account_closed]

  changeset :create_changeset, :create
  changeset :update_changeset, :update
end

By default, the standard name of :changset is used like normal within the store itself. To use no changeset, just provide the following:

defmodule CustomersApi do
  use RestApiBuilder, plural_name: :customers, singular_name: :customer, activate: :all

  provider RestApiBuilder.EctoSchemaStoreProvider, store: CustomerStore,
                                                   soft_delete: {:account_closed, true},
                                                   exclude: [:account_closed]

  changeset nil
end

You can also provide a default changeset for both create and update:

defmodule CustomersApi do
  use RestApiBuilder, plural_name: :customers, singular_name: :customer, activate: :all

  provider RestApiBuilder.EctoSchemaStoreProvider, store: CustomerStore,
                                                   soft_delete: {:account_closed, true},
                                                   exclude: [:account_closed]

  changeset :api_changeset
end

The changeset could also be changed progarmatically such as with an plug to be set based upon the using accessing the service. This is done by adding a :changeset value to the Plug.Conn assigns map.

defmodule CustomersApi do
  use RestApiBuilder, plural_name: :customers, singular_name: :customer, activate: :all, default_plugs: false
  import Plug.Conn

  provider RestApiBuilder.EctoSchemaStoreProvider, store: CustomerStore,
                                                   soft_delete: {:account_closed, true},
                                                   exclude: [:account_closed]

  plugs do
    plug :check_access_level
  end

  def check_access_level(%Plug.Conn{assigns: %{current_user: %{type: "admin"}}} = conn, _opts) do
    assign conn, :changeset, :admin_changeset
  end
  def check_access_level(conn, _opts), do: conn

  changeset :standard_user_changeset
end

Customizing the JSON Output content

The generation of the final message envelope is handled by the rest_api_builder library. However, this library does generate the map content that is used and set for record output. To give better control to the developer, the render_view_map function can be overloaded to customize the output.

By default render_view_map does the following:

 def render_view_map(record), do: whitelist(MyStore.to_map(record))

whitelist is function that filters Map content to the fields defined by the include and exclude settings of this provider. This function can be added to your resource module in order to append or completly replace how the output map is built. You will recieve the original Ecto model as input. This function will be applied on index, show, create, update actions. If you are defining a feature, you will need to call this function manually.

defmodule CustomersApi do
  use RestApiBuilder, plural_name: :customers, singular_name: :customer, activate: :all

  provider RestApiBuilder.EctoSchemaStoreProvider, store: CustomerStore

  def render_view_map(customer) do
    customer = Map.take customer, [:name, :email]

    if customer.account_closed do
      Map.put customer, :note, "This account is closed."
    else
      Map.put customer, :note, "This account is active."
    end
  end
end
You can’t perform that action at this time.