{"id":15063658,"url":"https://github.com/lucacorti/jsonapi_plug","last_synced_at":"2025-08-21T02:31:33.443Z","repository":{"id":57758467,"uuid":"527227503","full_name":"lucacorti/jsonapi_plug","owner":"lucacorti","description":"JSON:API library for Plug and Phoenix applications","archived":false,"fork":false,"pushed_at":"2025-08-20T07:35:54.000Z","size":1103,"stargazers_count":13,"open_issues_count":5,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-08-20T09:27:14.624Z","etag":null,"topics":["elixir","elixir-lang","elixir-library","elixir-phoenix","json-api"],"latest_commit_sha":null,"homepage":"https://hexdocs.pm/jsonapi_plug","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/lucacorti.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG-jsonapi.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-08-21T14:17:56.000Z","updated_at":"2025-08-20T07:35:51.000Z","dependencies_parsed_at":"2023-10-03T02:00:09.089Z","dependency_job_id":"33957b7b-7e3f-47c1-90ee-456b1d1913d4","html_url":"https://github.com/lucacorti/jsonapi_plug","commit_stats":{"total_commits":732,"total_committers":54,"mean_commits":"13.555555555555555","dds":0.6133879781420766,"last_synced_commit":"cbd215c0c0f58ccd6912f1513847cb39e5ee3b5d"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/lucacorti/jsonapi_plug","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucacorti%2Fjsonapi_plug","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucacorti%2Fjsonapi_plug/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucacorti%2Fjsonapi_plug/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucacorti%2Fjsonapi_plug/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucacorti","download_url":"https://codeload.github.com/lucacorti/jsonapi_plug/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucacorti%2Fjsonapi_plug/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271416855,"owners_count":24755973,"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-08-21T02:00:08.990Z","response_time":74,"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":["elixir","elixir-lang","elixir-library","elixir-phoenix","json-api"],"created_at":"2024-09-25T00:05:28.622Z","updated_at":"2025-08-21T02:31:33.436Z","avatar_url":"https://github.com/lucacorti.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSON:API library for Plug and Phoenix applications\n\nServer library to build [JSON:API](http://jsonapi.org) compliant REST APIs.\n\n## JSON:API Support\n\nThis library currently implements version `1.0` of the [JSON:API][json:api] specification.\nHowever, to support resource creation alongside included resources, `JSON:API 1.1` `lid` is supported.\n\n## Documentation\n\n- Full documentation can be found on [hexdocs.pm][jsonapi_plug-hexdocs]\n\nFor the `JSON:API` specification documentation as well as other client and server implementations:\n\n- [JSON:API][json:api]\n- [JSON:API Specification (v1.0)][json:api-1.0]\n- [JSON:API Specification (v1.1)][json:api-1.1]\n\n## Quickstart\n\n### Installation\n\nAdd the following line to your `mix.deps` file with the desired version to install `jsonapi_plug`.\n\n```elixir\ndefp deps do [\n  ...\n  {:jsonapi_plug, \"~\u003e 2.0\"}\n  ...\n]\n```\n\n### Upgrading\n\nUpgrading the library should be safe for minor and patch version upgrades, it's still a good practice\nto check the [changelog][changelog] for more information on the release content. For major version\nupgrades, breaking changes should be expected, and the [upgrade guide][upgrade] contains instructions\non upgrading between major releases of the library.\n\n### Configuration\n\nYou start by declaring one or more APIs. APIs are collections of endpoints that\nshare a common configuration:\n\n```elixir\ndefmodule MyApp.API do\n  use JSONAPIPlug.API, otp_app: :my_app\nend\n```\n\nSee the `JSONAPIPlug.API` module documentation to learn how to customize your APIs\nvia application configuration of your app.\n\n### Resources\n\nTo start accept requests and serving responses, you need to define `JSON:API` resources.\nResources can be any struct `@derive`-ing the `JSONAPIPlug.Resource` protocol:\n\n```elixir\ndefmodule MyApp.Post do\n  use Ecto.Schema\n\n  @type t :: %__MODULE__{id: pos_integer(), body: String.t(), title: String.t()}\n\n  @derive {\n    JSONAPIPlug.Resource,\n    type: \"post\",\n    attributes: [:title, :text, :excerpt]\n  }\n  schema \"posts\" do\n    field :title\n    field :text\n  end\n\n  ...\nend\n```\n\nSee `JSONAPIPlug.Resource` for the complete documentation of options you can pass to `@derive`,\nincluding how to control serialization and deserialization, and add related resources.\n\nAlso, three optional protocols are available to allow further customization of resources.\n\n- Resource attribute custom serialization and deserialization: `JSONAPIPlug.Resource.Attribute`\n- Resource link generation: `JSONAPIPlug.Resource.Links`\n- Resource link generation: `JSONAPIPlug.Resource.Meta`\n\n### Usage with Phoenix\n\nTo serve JSON:API resources in Phoenix, you need to define routes in your router:\n\n```elixir\ndefmodule MyAppWeb.Router do\n  ...\n  resource \"/posts\", MyApp.PostsController, only: [:create, :index, :show]\n  patch \"/posts/:id\", MyApp.PostsController, :update\nend\n```\n\nIn order to parse `JSON:API` requests from clients you need to add the `JSONAPIPlug.Plug` plug to each of your\nphoenix controllers handling requests for a specific resource. This will take care of ensuring `JSON:API` request\ncompliance and will return errors for malformed requests.\n\nWhen a valid request processed, the `:jsonapi_plug` `Plug.Conn` private field will be populated in the controller.\n\nYou can learn all about advanced request handling, including custom filtering, relationships inclusion, pagination\nand sparse fields support by reading the `JSONAPIPlug.Plug` module documentation.\n\nOnce you receive a request in your controller and load data, you just call render to send a response:\n\n```elixir\n  defmodule MyAppWeb.PostsController do\n    ...\n    plug JSONAPIPlug.Plug, api: MyApp.API, path: \"posts\", resource: MyApp.Post\n    ...\n\n    def create(%Conn{private: %{jsonapi_plug: %JSONAPIPlug{} = jsonapi_plug}} = conn, params) do\n      post = ...create a post using jsonapi_plug parsed parameters...\n      render(conn, \"create.json\", %{data: post})\n    end\n\n    def index(%Conn{private: %{jsonapi_plug: %JSONAPIPlug{} = jsonapi_plug}} = conn, _params) do\n      posts = ...load data using jsonapi_plug parsed parameters...\n      render(conn, \"index.json\", %{data: post})\n    end\n\n    def show(%Conn{private: %{jsonapi_plug: %JSONAPIPlug{} = jsonapi_plug}} = conn, _params) do\n      post = ...load data using jsonapi_plug parsed parameters...\n      render(conn, \"show.json\", %{data: post})\n    end\n\n    def update(%Conn{private: %{jsonapi_plug: %JSONAPIPlug{} = jsonapi_plug}} = conn, params) do\n      post = ...update a post using jsonapi_plug parsed parameters...\n      render(conn, \"update.json\", %{data: post})\n    end\n  end\n```\n\nFor phoenix to dispatch this for rendering you need to add this code to your `MyAppWeb` module:\n\n```elixir\ndef MyAppWeb do\n ...\n\n  def json_api do\n    quote do\n      use JSONAPIPlug.Phoenix.Component\n    end\n  end\n\n...\nend\n```\n\nand define a corresponding rendering template module:\n\n```elixir\ndefmodule SibillWeb.PostsJSON do\n  @moduledoc false\n\n  use MyAppWeb, :json_api\nend\n```\n\nalternatively you can skip these steps by calling `JSONAPIPlug.render/4` directly instead of `render/3` in you controller:\n\n```elixir\n...\n    def show(%Conn{private: %{jsonapi_plug: %JSONAPIPlug{} = jsonapi_plug}} = conn, _params) do\n      post = ...load data using jsonapi_plug parsed parameters...\n      JSONAPIPlug.render(conn, post \\\\ nil, meta \\\\ nil, options \\\\ [])\n    end\n...\n```\n\n### Usage with Plug\n\nIf you have a `Plug` application, assuming you already set up routing you can call `JSONAPIPlug.render/4` in your\npipeline to generate a `JSONAPI.Document` with your data for the client.\n\n```elixir\nJSONAPIPlug.render(conn, post)\n|\u003e Jason.encode!()\n```\n\nRender returns a `JSONAPI.Document`, that is serializable to JSON via `Jason`.\n\n## Contributing\n\n- This project was born as a fork of the [jsonapi][jsonapi-fork]\nlibrary but has since been completely rewritten and is now a completely different project.\n- PRs for new features, bug fixes, documentation and tests are welcome\n- If you are proposing a large feature or change, please open an issue for discussion\n\n[changelog]: https://hexdocs.pm/jsonapi_plug/changelog.html\n[json:api-1.0]: https://jsonapi.org/format/1.0/\n[json:api-1.1]: https://jsonapi.org/format/1.1/\n[json:api]: https://jsonapi.org\n[jsonapi-fork]: https://github.com/beam-community/jsonapi\n[jsonapi_plug-hexdocs]: https://hexdocs.pm/jsonapi_plug\n[upgrade]: https://hexdocs.pm/jsonapi_plug/upgrading.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucacorti%2Fjsonapi_plug","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucacorti%2Fjsonapi_plug","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucacorti%2Fjsonapi_plug/lists"}