Versioning provides a way for API's to remain backward compatible without the headache.

This is done through use of a "versioning schema" that translates data through a series of steps from its current version to the target version. This technique is well described in the article APIs as infrastructure: future-proofing Stripe with versioning.

The basic rule is each API version in the schema must only ever concern itself with creating a set of change modules associated with the version below/above it. This contract ensures that we can continue to translate data to legacy versions without enormous effort.

The package can be installed by adding versioning to your list of dependencies in mix.exs:

def deps do
  [
    {:versioning, "~> 0.4"}
  ]
end

See HexDocs for additional documentation.

For a more in-depth example, please check out the Getting Started page.

We build a schema to describe updates to our API through versions, types, and changes.

defmodule MyAPI.Versioning do
  use Versioning.Schema

  version("1.2.0", do: [])

  version "1.1.0" do
    type "Post" do
      change(MyAPI.Changes.PostStatusChange)
    end
  end

  version("1.0.0", do: [])
end

We build a change module to perform data modifications.

defmodule MyAPI.Changes.PostStatusChange do
  use Versioning.Change

  @desc """
  The boolean field "active" was removed in favour of the enum "status".
  """

  def down(versioning, _opts) do
    case Versioning.pop_data(versioning, "status") do
      {"active", versioning} -> Versioning.put_data(versioning, "active", true)
      {_, versioning} -> Versioning.put_data(versioning, "active", false)
    end
  end

  def up(versioning, _opts) do
    case Versioning.pop_data(versioning, "active") do
      {true, versioning} -> Versioning.put_data(versioning, "status", "active")
      {false, versioning} -> Versioning.put_data(versioning, "status", "hidden")
      {_, versioning} -> versioning
    end
  end
end

We create versionings to run against our schema. Here, we want to change our post data from version 1.2.0 to 1.0.0. We can then run our versioning against the schema, which will return a modified versioning with our change modules run.

versioning = Versioning.new(%Post{}, "1.2.0", "1.0.0")
MyAPI.Versioning.run(versioning)

Versioning provides extensive support for usage with Phoenix. Checkout the Phoenix Usage page for more details.