Versioning.Controller (Versioning v0.4.1) View Source

A set of functions used with Phoenix controllers.

Typically, this module should be imported into your controller modules. In a normal phoenix application, this can usually be done with the following:

defmodule YourAppWeb do
# ...

  def controller do
    quote do
      use Phoenix.Controller, namespace: MyAppWeb

      # ...

      import Versioning.Controller

      # ...
    end
  end
end

Please see the documentation at Phoenix.Controller for details on how to set up a typical controller.

This module is mainly used to convert raw params from the version that the request data represents, to the latest version that your "context" application expects.

Example

Below is an example of how to use versioning in a typical controller:

defmodule MyController do
  use MyAppWeb, :controller

  plug Versioning.Plug, schema: MyVersioningSchema

  def update(conn, %{"id" => id, "user" => params}) do
    with {:ok, params} <- params_version(conn, params, "User"),
         {:ok, user} <- Blog.fetch_user(id),
         {:ok, user} <- Blog.update_user(user) do
      render(conn, "show.json", user: user)
    end
  end
end

The params_version/3 function accepts a conn, a set of params representing whatever version of the data the user uses, as well as the type of the data. It will run the params through your schema, returning the results.

Link to this section Summary

Functions

apply_version(conn, header \\ "x-api-version", fallback \\ :latest)

Applies a version using the header or fallback.

fetch_schema(conn)

Fetches the current schema.

fetch_schema!(conn)

Fetches the current schema or errors if empty.

fetch_version(conn)

Fetches the current request version.

fetch_version!(conn)

Fetches the current request version or errors if empty.

params_version(conn, params, type)

Performs versioning on the params using the given type.

put_schema(conn, schema)

Stores the schema for versioning.

put_version(conn, version)

Stores the request version.

Link to this section Functions

apply_version(conn, header \\ "x-api-version", fallback \\ :latest)

Specs

apply_version(Plug.Conn.t(), binary(), :latest | {module(), atom()}) ::
  Plug.Conn.t()

Applies a version using the header or fallback.

The schema must already be stored on the conn to use this function.

The fallback is used if the header is not present. Its value can be :latest, representing the latest version on the schema, or a {module, function}. This module and function will be called with the conn.

fetch_schema(conn)

Specs

fetch_schema(Plug.Conn.t()) :: {:ok, Versioning.Schema.t()} | :error

Fetches the current schema.

Returns {:ok, schema} on success, or :error if no schema exists.

Examples

iex> conn = Versioning.Controller.put_schema(conn, MySchema)
iex> Versioning.Controller.fetch_schema(conn)
{:ok, MySchema}

fetch_schema!(conn)

Specs

fetch_schema!(Plug.Conn.t()) :: Versioning.Schema.t()

Fetches the current schema or errors if empty.

Returns schema or raises a Versioning.MissingSchemaError.

Examples

iex> conn = Versioning.Controller.put_schema(conn, MySchema)
iex> Versioning.Controller.fetch_schema!(conn)
MySchema

fetch_version(conn)

Specs

fetch_version(Plug.Conn.t()) :: {:ok, binary()} | :error

Fetches the current request version.

Returns {:ok, version} on success, or :error if no version exists.

Examples

iex> conn = Versioning.Controller.put_version(conn, "1.0.0")
iex> Versioning.Controller.fetch_version(conn)
{:ok, "1.0.0"}

fetch_version!(conn)

Specs

fetch_version!(Plug.Conn.t()) :: Versioning.Schema.t()

Fetches the current request version or errors if empty.

Returns version or raises a Versioning.MissingVersionError.

Examples

iex> conn = Versioning.Controller.put_schema(conn, "1.0.0")
iex> Versioning.Controller.fetch_version!(conn)
"1.0.0"

params_version(conn, params, type)

Specs

params_version(Plug.Conn.t(), map(), binary()) ::
  {:ok, map()} | {:error, :bad_version}

Performs versioning on the params using the given type.

The schema and request version must already be stored on the conn to use this function.

Returns {:ok, params} with the new versioned params, or {:error, :bad_version} if the schema does not contain the version requested.

put_schema(conn, schema)

Specs

put_schema(Plug.Conn.t(), Versioning.Schema.t()) :: Plug.Conn.t()

Stores the schema for versioning.

Examples

Versioning.Controller.put_schema(conn, MySchema)

put_version(conn, version)

Specs

put_version(Plug.Conn.t(), binary()) :: Plug.Conn.t()

Stores the request version.

Examples

Versioning.Controller.put_version(conn, "1.0.0")