Params Modules for Phoenix

We introduce Params modules as a pattern to validate and massage a controller action's params into data that can be passed to contexts.

API parameters are so easy to work with when they can all be handled by a schema's changeset. This is often the case when dealing with simple RESTful endpoints which directly map an API resource to a schema.

POST /addresses
{
  "line1": "225 E 60th St",
  "city": "New York",
  "state": "NY",
  "zip_code": "10022",
  "country": "USA"
}

defmodule MyAppWeb.AddressController do
  use MyAppWeb, :controller

  def create(conn, params) do
    with {:ok, address} <- MyApp.Addresses.create(params) do
      send_resp(conn, :created, "")
    end
  end
end

In many other cases, an endpoint receives params representing pieces of multiple different schemas; or no schema at all.

Logging in

To log in a user, /login receives a user's email address, password, and answers to their security questions.

POST /login
{
  "email": "mateusz@example.com"
  "password": "abc123",
  "security_answers": [
    {
      "security_question_id": "12",
      "text": "Mniszków"
    },
    {
      "security_question_id": "23",
      "text": "basketball"
    }
  ]
}

defmodule MyAppWeb.LoginController do
  use MyAppWeb, :controller

  alias MyApp.{Login, StrongAuth}

  def create(conn, params) do
    with {:ok, user} <- Login.authenticate(params["email"], params["password"]),
         :ok <- StrongAuth.authenticate(user, params["security_answers"]) do
      send_resp(conn, :created, "")
    end
  end
end

Unlike our address example, these parameters don't map directly to some underlying changeset function. The email and password are passed to Login.authenticate/2 to find a user, and then that user and the security questions are passed to StrongAuth.authenticate/2.

So, we want to validate, in the web layer, that we've received the data needed by our functions before calling them.

One way to do this is to pattern match the params in the action:

def create(conn, %{"email" => email, "password" => password, "security_answers" => security_answers}) do
  # ...
end

This approach currently doesn't validate the structure of the nested security_answers. Doing so, and more complex cases can quickly clutter the controller. Additionally, if any part of the pattern match fails, a blanket error response will be returned instead of indicating which part of the request body was malformed.

Params modules

We can use the Params module pattern to validate the structure of the incoming params.

defmodule MyAppWeb.LoginController do
  use MyAppWeb, :controller

  alias MyApp.{Login, StrongAuth}

  def create(conn, params) do
    with {:ok, params} <- MyAppWeb.LoginParams.prepare(params),
         {:ok, user} <- Login.authenticate(params.email, params.password),
         :ok <- StrongAuth.authenticate(user, params.security_answers) do
      send_resp(conn, :created, "")
    end
  end
end

Now, our controller stays slim, and we've made sure we have the data needed by the contexts before continuing.

Here's what LoginParams looks like:

# my_app_web/params/login_params.ex
defmodule MyAppWeb.LoginParams do
  use Ecto.Schema
  import Ecto.Changeset

  @primary_key false

  embedded_schema do
    field(:email, :string)
    field(:password, :string)

    embeds_many(:security_answers, SecurityAnswerParams)
  end

  def prepare(params) do
    changeset(params) |> apply_action(:insert)
  end

  def changeset(login_params \\ %__MODULE__{}, params) do
    login_params
    |> cast(params, [:email, :password])
    |> cast_embed(:security_answers, required: true)
    |> validate_required([:email, :password])
    |> validate_length(:security_answers, is: 2)
  end
end

As you can see, params modules are simple Ecto.Schema which use embedded_schema. Using the usual Ecto.Changeset functions, they validate the structure of the data and supports nesting.

Params modules expose a prepare/1 function which will return an :ok tuple with validated params, or an :error tuple with an invalid changeset for the controller to handle.

Using the invalid changeset, the controller can return a very specific error message to indicate which part of the params were malformed.

Massaging params

We can also use params modules to apply simple transformations — such as trimming whitespace around an email — or complex transformations.

Say our login API accepts a list of %{text:, security_question_id:} for security answers, while StrongAuth.authenticate/2 requires a list of %{answer:, security_question_id:}. We could modify LoginParams to transform the data if it's valid:

defmodule MyAppWeb.LoginParams do
  # ...

  def prepare(params) do
    changeset(params)
    |> apply_action(:insert)
    |> case do
      {:ok, params} -> {:ok, transform(params)}
      {:error, changeset} -> {:error, changeset}
    end
  end

  def transform(params) do
    security_answers =
      Enum.map(params.security_answers, fn security_answer ->
        %{
          security_question_id: security_answer.security_question_id,
          answer: security_answer.text
        }
      end)

    Map.put(params, :security_answers, security_answers)
  end
end

This flexibility allow the format of the API to be entirely decoupled from the format of the rest of the business logic.

Params modules, the Phoenix way

Way 1: We can cleanup some of the boilerplate logic that comes with params modules the same way we do for phoenix controllers, channels, views, and routers. First we add a block to lib/my_app_web.ex:

defmodule MyAppWeb do
  # ...

  def params do
    quote do
      use Ecto.Schema
      import Ecto.Changeset

      @primary_key false
    end
  end

  # ...
end

And now we can use it in each of our params modules:

defmodule MyAppWeb.LoginParams do
  use MyAppWeb, :params

  # ...
end

Way 2: Params modules follow the same naming convention as Phoenix controllers and views:

# my_app_web/controllers/login_controller.ex
defmodule MyAppWeb.LoginController do

# my_app_web/params/login_params.ex
defmodule MyAppWeb.LoginParams do

A tool in the tool belt

Params modules are a pattern we can reach for when dealing with params structures that aren't (and shouldn't be) handled by a phoenix context. Using them in every controller action would add unnecessary complexity.

With that said, here are some reasons you might want to try out params modules in your project:

  • Params modules keep param validation and massaging out of your controller.

  • Params modules keep web-layer concerns out of your contexts.

  • Params modules use familiar Ecto schemas and Phoenix conventions. There's no magic!

  • Params modules convert string keys to atoms so using string keys stops at the web layer.

  • Params modules are a convention so using them doesn't add any dependencies to your project.

Shout-outs

A massive inspiration for this work came from vic/params so be sure to check it out. Params modules take a step back from what the params package provides in favour of: being a pattern instead of a dependency, explicitly using familiar Ecto schemas instead of a new DSL, and the flexibility to transform instead of only validating the params structure.

If all you want is a way to whitelist params like Rails does with Strong Parameters, I recommend checking out Lucas de Queiroz Alves' Phoenix |> Strong Params.


Discuss on Twitter 💬