{"id":13509087,"url":"https://github.com/sticksnleaves/versionary","last_synced_at":"2025-10-11T20:16:05.241Z","repository":{"id":46818800,"uuid":"85418242","full_name":"sticksnleaves/versionary","owner":"sticksnleaves","description":"Plug for API versioning","archived":false,"fork":false,"pushed_at":"2021-09-23T17:53:53.000Z","size":170,"stargazers_count":40,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-24T01:28:04.613Z","etag":null,"topics":["api-versioning","elixir","elixir-lang","elixir-phoenix","elixir-plug"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/versionary","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sticksnleaves.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-18T17:08:55.000Z","updated_at":"2024-06-23T06:00:30.000Z","dependencies_parsed_at":"2022-09-12T02:30:42.381Z","dependency_job_id":null,"html_url":"https://github.com/sticksnleaves/versionary","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/sticksnleaves/versionary","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sticksnleaves%2Fversionary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sticksnleaves%2Fversionary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sticksnleaves%2Fversionary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sticksnleaves%2Fversionary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sticksnleaves","download_url":"https://codeload.github.com/sticksnleaves/versionary/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sticksnleaves%2Fversionary/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279008579,"owners_count":26084480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-versioning","elixir","elixir-lang","elixir-phoenix","elixir-plug"],"created_at":"2024-08-01T02:01:02.780Z","updated_at":"2025-10-11T20:16:05.226Z","avatar_url":"https://github.com/sticksnleaves.png","language":"Elixir","funding_links":[],"categories":["REST and API"],"sub_categories":[],"readme":"# Versionary\n\nAdd versioning to your Elixir Plug and Phoenix built API's.\n\n[![CI](https://github.com/sticksnleaves/versionary/actions/workflows/ci.yaml/badge.svg)](https://github.com/sticksnleaves/versionary/actions/workflows/ci.yaml)\n[![Coverage Status](https://coveralls.io/repos/github/sticksnleaves/versionary/badge.svg?branch=master)](https://coveralls.io/github/sticksnleaves/versionary?branch=master)\n[![Module Version](https://img.shields.io/hexpm/v/versionary.svg)](https://hex.pm/packages/versionary)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/versionary/)\n[![Total Download](https://img.shields.io/hexpm/dt/versionary.svg)](https://hex.pm/packages/versionary)\n[![License](https://img.shields.io/hexpm/l/versionary.svg)](https://github.com/sticksnleaves/versionary/blob/master/LICENSE.md)\n[![Last Updated](https://img.shields.io/github/last-commit/sticksnleaves/versionary.svg)](https://github.com/sticksnleaves/versionary/commits/master)\n\n\n## Installation\n\nThe package can be installed by adding `:versionary` to your list of dependencies\nin `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:versionary, \"~\u003e 0.3\"}\n  ]\nend\n```\n\n## Usage\n\n```elixir\ndef MyAPI.Router do\n  use Plug.Router\n\n  plug Versionary.Plug.VerifyHeader, versions: [\"application/vnd.app.v1+json\"]\n\n  plug Versionary.Plug.EnsureVersion, handler: MyAPI.MyErrorHandler\n\n  plug :match\n  plug :dispatch\nend\n```\n\n## MIME Support\n\nIt's possible to verify versions against configured MIME types. If multiple MIME\ntypes are passed and at least one matches the version will be considered valid.\n\n```elixir\nconfig :mime, :types, %{\n  \"application/vnd.app.v1+json\" =\u003e [:v1],\n  \"application/vnd.app.v2+json\" =\u003e [:v2]\n}\n```\n\n```elixir\nplug Versionary.Plug.VerifyHeader, accepts: [:v1, :v2]\n```\n\nPlease note that whenever you change media type configurations you must\nrecompile the `mime` library.\n\nTo force `mime` to recompile run `mix deps.clean --build mime`.\n\n## Identifying Versions\n\nWhen a version has been verified `:version` and `:raw_version` private keys will\nbe added to the conn. These keys will contain version that has been verified.\n\nThe `:version` key may contain either the string version provided by the\nrequest or, if configured, the MIME extension. The `:raw_version` key will\nalways contain the string version provided by the request.\n\n## Phoenix\n\nVersionary is just a plug. That means Versionary works with Phoenix out of the\nbox. However, if you'd like Versionary to render a Phoenix error view when\nverification fails use `Versionary.Plug.PhoenixErrorHandler`.\n\n```elixir\ndefmodule MyAPI.Router do\n  use MyAPI.Web, :router\n\n  pipeline :api do\n    plug Versionary.Plug.VerifyHeader, accepts: [:v1, :v2]\n\n    plug Versionary.Plug.EnsureVersion, handler: Versionary.Plug.PhoenixErrorHandler\n  end\n\n  scope \"/\", MyAPI do\n    pipe_through :api\n\n    get \"/my_controllers\", MyController, :index\n  end\nend\n```\n\n### Handling Multiple Versions\n\nYou can pattern match which version of a controller action to run based on the\n`:version` (or `:raw_version`) private key provided by the conn.\n\n```elixir\ndefmodule MyAPI.MyController do\n  use MyAPI, :controller\n\n  def index(%{private: %{version: [:v1]}} = conn, _params) do\n    render(conn, \"index.v1.json\", %{})\n  end\n\n  def index(%{private: %{version: [:v2]}} = conn, _params) do\n    render(conn, \"index.v2.json\", %{})\n  end\nend\n```\n\n## Plug API\n\n### [Versionary.Plug.VerifyHeader](https://hexdocs.pm/versionary/Versionary.Plug.VerifyHeader.html)\n\nVerify that the version passed in to the request as a header is valid. If the\nversion is not valid then the request will be flagged.\n\nThis plug will not handle an invalid version. If you would like to halt the\nrequest and handle an invalid version please see\n[`Versionary.Plug.EnsureVersion`](https://hexdocs.pm/versionary/Versionary.Plug.EnsureVersion.html).\n\n#### Options\n\n`accepts` - a list of strings or atoms representing versions registered as\nMIME types. If at least one of the registered versions is valid then the\nrequest is considered valid.\n\n`versions` - a list of strings representing valid versions. If at least one of\nthe provided versions is valid then the request is considered valid.\n\n`header` - the header used to provide the requested version (Default: `Accept`)\n\n### [Versionary.Plug.EnsureVersion](https://hexdocs.pm/versionary/Versionary.Plug.EnsureVersion.html)\n\nChecks to see if the request has been flagged with a valid version. If the\nversion is valid, the request continues, otherwise the request will halt and the\nhandler will be called to process the request.\n\n#### Options\n\n`handler` - the module used to handle a request with an invalid version\n(Default: [Versionary.Plug.ErrorHandler](https://hexdocs.pm/versionary/Versionary.Plug.ErrorHandler.html))\n\n### [Versionary.Plug.Handler](https://hexdocs.pm/versionary/Versionary.Plug.Handler.html)\n\nBehaviour for handling requests with invalid versions. You can create your own\ncustom handler with this behaviour.\n\n# Copyright and License\n\nCopyright (c) 2017 Sticksnleaves\n\nThis library is licensed under the [MIT license](./LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsticksnleaves%2Fversionary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsticksnleaves%2Fversionary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsticksnleaves%2Fversionary/lists"}