{"id":21657243,"url":"https://github.com/cantido/liberator","last_synced_at":"2025-04-10T03:55:44.562Z","repository":{"id":40494128,"uuid":"300438517","full_name":"Cantido/liberator","owner":"Cantido","description":"An Elixir library for building applications with HTTP","archived":false,"fork":false,"pushed_at":"2025-03-18T15:40:48.000Z","size":702,"stargazers_count":34,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T03:55:38.416Z","etag":null,"topics":["elixir","elixir-library","hacktoberfest","http","liberator","phoenix","plug","webmachine"],"latest_commit_sha":null,"homepage":"https://hex.pm/packages/liberator/","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cantido.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"code_of_conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-01T22:14:51.000Z","updated_at":"2025-03-18T15:40:45.000Z","dependencies_parsed_at":"2023-02-09T17:50:13.557Z","dependency_job_id":"d1e69f9a-7826-49f4-9bdf-58a66aa36988","html_url":"https://github.com/Cantido/liberator","commit_stats":{"total_commits":427,"total_committers":3,"mean_commits":"142.33333333333334","dds":0.2857142857142857,"last_synced_commit":"508e343167975ac49af48c8e5da28663d00fc0fd"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cantido%2Fliberator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cantido%2Fliberator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cantido%2Fliberator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cantido%2Fliberator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cantido","download_url":"https://codeload.github.com/Cantido/liberator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248155001,"owners_count":21056542,"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","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":["elixir","elixir-library","hacktoberfest","http","liberator","phoenix","plug","webmachine"],"created_at":"2024-11-25T09:20:10.082Z","updated_at":"2025-04-10T03:55:44.542Z","avatar_url":"https://github.com/Cantido.png","language":"Elixir","readme":"\u003c!--\nSPDX-FileCopyrightText: 2024 Rosa Richter\n\nSPDX-License-Identifier: CC-BY-SA-4.0\n--\u003e\n\n# Liberator\n\n[![Hex.pm](https://img.shields.io/hexpm/v/liberator)](https://hex.pm/packages/liberator/)\n[![builds.sr.ht status](https://builds.sr.ht/~cosmicrose/liberator.svg)](https://builds.sr.ht/~cosmicrose/liberator?)\n[![liberapay goals](https://img.shields.io/liberapay/goal/rosa.svg?logo=liberapay)](https://liberapay.com/rosa)\n[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg)](https://github.com/RichardLitt/standard-readme)\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](code_of_conduct.md)\n\nAn Elixir library for building applications with HTTP.\n\nLiberator is a port of the [Liberator](https://clojure-liberator.github.io/liberator/) Clojure library\nthat allows you to define a controller that adheres to the HTTP spec by providing just a few pieces of information.\nIt implements a [decision graph] of simple boolean questions that lead your app to the correct HTTP status codes.\n\nWhile Phoenix and Plug make routing easy, they don't do anything with content negotiation,\nor cache management, or existence checks, or anything like that,\nbeyond calling the right controller function based on the HTTP method.\nThere are a lot of decisions to make before returning the right HTTP status code,\nbut Phoenix doesn't give you any additional power to do so.\nLiberator does.\n\n## Install\n\nThis package is [available in Hex](https://hex.pm/packages/liberator).\nInstall it by adding `liberator` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:liberator, \"~\u003e 1.4.0\"}\n  ]\nend\n```\n\nDocumentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)\nand can be found online at [https://hexdocs.pm/liberator](https://hexdocs.pm/liberator).\n\n## Usage\n\nFor a basic `GET` endpoint, you can define an entire module in five lines of code.\nTechnically you don't even need to implement these two,\nsince sensible defaults are provided.\n\n```elixir\ndefmodule MyFirstResource do\n  use Liberator.Resource\n\n  def available_media_types(_), do: [\"text/plain\"]\n  def handle_ok(_), do: \"Hello world!\"\nend\n```\n\nIt doesn't look like much, but behind the scenes,\nLiberator navigated a [decision graph] of content negotation, cache management,\nand existence checks before returning 200 OK.\nLiberator finds the best media type you support,\nand automatically encodes your return value.\nJSON is supported out of the box, and any additional types\ncan be provided in a line of the config.\n\n```elixir\n# in config.exs\nconfig :liberator, media_types: %{\n  \"application/json\" =\u003e Jason,\n  \"application/xml\" =\u003e MyXmlCodec\n}\n\n# in your main body of code\ndefmodule MyJsonOrXmlResource do\n  use Liberator.Resource\n\n  def available_media_types(_), do: [\"application/json\", \"application/xml\"]\n  def handle_ok(_), do: %{message: \"hi!\"}\nend\n```\n\nA Liberator Resource implements the [Plug](https://github.com/elixir-plug/plug) spec,\nso you can forward requests to it in frameworks like Phoenix:\n\n```elixir\nscope \"/api\", MyApp do\n  pipe_through [:api]\n\n  forward \"/resources\", MyFirstResource\nend\n```\n\nYour results from questions are aggregated into the `:assigns` map on the conn,\nso you don't have to access data more than once.\n\n```elixir\ndefmodule MaybeExistingResource do\n  use Liberator.Resource\n\n  def exists?(conn) do\n    case MyApp.Repo.get(MyApp.Post, conn.params[\"id\"]) do\n      nil -\u003e false\n      post -\u003e %{post: post}\n    end\n  end\n  def handle_ok(conn), do: conn.assigns[:post]\nend\n```\n\nSee more in the [Getting Started guide](guides/getting_started.md),\nand in the [documentation for `Liberator.Resource`](https://hexdocs.pm/liberator/Liberator.Resource.html).\nYou can also see an example controller built with Liberator at [the `liberator_example` project](https://github.com/Cantido/liberator_example/).\n\n## Maintainer\n\nThis project was developed by [Rosa Richter](https://about.me/rosa.richter).\nYou can get in touch with her on [Keybase.io](https://keybase.io/cantido).\n\n## Thanks\n\nThanks to the maintainers of the original Clojure [liberator] project,\n[Philipp Meier] and [Malcolm Sparks], for creating such a handy tool.\nTheir great documentation was an immense help in porting it to Elixir.\nAnd thanks to the maintainers of Erlang's [webmachine](https://github.com/basho/webmachine) for inspiring them!\n\n[Philipp Meier]: https://github.com/ordnungswidrig\n[Malcolm Sparks]: https://github.com/malcolmsparks\n[liberator]: https://github.com/clojure-liberator/liberator\n[webmachine]: https://github.com/basho/webmachine\n\n## Contributing\n\nQuestions and pull requests are more than welcome.\nI follow Elixir's tenet of bad documentation being a bug,\nso if anything is unclear, please [file an issue](https://todo.sr.ht/~cosmicrose/liberator) or ask on the [mailing list]!\nIdeally, my answer to your question will be in an update to the docs.\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md) for all the details you could ever want about helping me with this project.\n\nNote that this project is released with a Contributor [Code of Conduct].\nBy participating in this project you agree to abide by its terms.\n\n## License\n\nMIT License\n\nCopyright 2024 Rosa Richter\n\nThis program is free software: you can redistribute it and/or modify\nit under the terms of the GNU Affero General Public License as\npublished by the Free Software Foundation, either version 3 of the\nLicense, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU Affero General Public License for more details.\n\nYou should have received a copy of the GNU Affero General Public License\nalong with this program.  If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n\n[Code of Conduct]: code_of_conduct.md\n[decision graph]: guides/default_decision_tree.svg\n[mailing list]: https://lists.sr.ht/~cosmicrose/liberator\n","funding_links":["https://liberapay.com/rosa"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcantido%2Fliberator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcantido%2Fliberator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcantido%2Fliberator/lists"}