Skip to content
Versioning provides a way for Elixir API's to remain backward compatible without the headache.
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.
guides
lib
test
.formatter.exs
.gitignore
.travis.yml
CHANGELOG.md
LICENSE
README.md
mix.exs
mix.lock

README.md

Versioning

Build Status Versioning Version

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.

Installation

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

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

Documentation

See HexDocs for additional documentation.

Example

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)

Phoenix Usage

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

You can’t perform that action at this time.