Jsonapi_plug - JSON:API library for Plug and Phoenix applications


I’ve just published the first version of a new JSON:API library. This project was born as a fork of the jsonapi library (GitHub - beam-community/jsonapi: JSON:API Serializer and Query Handler for Elixir) but has since been almost completly rewritten and is a different project.

What jsonapi_plug has to offer to users of Phoenix/Plug for building JSON:API compliant APIs:

  • An extensible system based on behaviours to convert JSON:API payloads and query parameters from/to whatever format best suits the library user. Default implementations are provided to convert payloads and query parameters to an Ecto friendly format, which is probably the most common scenario for the data source of APIs in Phoenix based applications. Behaviours are available to customize parsing and/or easily parse non-standard specified query parameters (filter, page).

  • Ability to have multiple APIs with different configurations sourced from the hosting application configuration to avoid single global configuration rigidity. This allows to serve multiple different APIs from a single Phoenix/Plug application instance.

  • A declarative resource system allowing users to control rendering, rename fields between JSON:API payloads and internal data, customize (de)serialization of fields values and more without writing additional business logic code.

I’ve been using this for some time in production, but I’d love to get some feedback. It currently targets JSON:API 1.0, but I’d love to add support for the recently finalized JSON:API 1.1 spec.


Totally forgot to add links:


Hi lucacorti,

Do you have a test project to understand the implementation, particularly regarding the controller part?

Thanks in advance for the feedback.



Unfortunately I don’t have a sample app.

The documentation however contains a very basic example of a resource definition, including code you need to add to the controller.

If you are struggling with anything specific I’m happy to help.



Thanks for your reply.

I don’t understand the sentence ‘…create a post using jsonapi_plug parsed parameters…’, what should I do in this case?

Do you have a sample in this case ?


In your controller function conn.private.jsonapi_plug is a struct that contains the parsed request data.

The params field contains the resource attributes and relationships. You can pass that to your business logic to create the resource. By default data is parsed in an ecto compatible format. If you are not using ecto, you need to provide your own implementation to parse it differently.

I guess the documentation could be more explicit about this.