View Source JSON:API library for Plug and Phoenix applications
Server library to build JSON:API compliant REST APIs.
JSON:API Support
This library currently implements version 1.0
of the JSON:API specification.
Documentation
Quickstart
Installation
Add the following line to your mix.deps
file with the desired version to install jsonapi_plug
.
defp deps do [
...
{:jsonapi_plug, "~> 1.0"}
...
]
Configuration
You start by declaring one or more APIs. APIs are collections of endpoints that share a common configuration:
defmodule MyApp.API do
use JSONAPIPlug.API, otp_app: :my_app
end
See the JSONAPIPlug.API
module documentation to learn how to customize your APIs
via application configuration of your app.
Receiving requests
In order to parse JSON:API
requests from clients you need to add the JSONAPIPlug.Plug
plug to each of your plug pipelines or phoenix controllers handling requests for a specific resource:
defmodule MyApp.PostsController do
...
plug JSONAPIPlug.Plug, api: MyApp.API, resource: MyApp.PostResource
...
end
This will take care of ensuring JSON:API
specification compliance and will return errors for invalid requests.
The :api
option expects a module using JSONAPI.API
for configuration.
The :resource
option expects a module using JSONAPIPlug.Resource
to convert to/from JSON:API
format.
When requests are processed, the :jsonapi_plug
connection private field is populated with the parsed request.
See the JSONAPIPlug.Plug
module documentation for usage and options.
Serving responses
To start serving responses, you need to have some data to return to clients:
defmodule MyApp.Post do
@type t :: %__MODULE__{id: pos_integer(), body: String.t(), title: String.t()}
@enforce_keys [:id, :body, :title]
defstruct [:id, :body, :title]
end
and define a resource module to render your resource:
defmodule MyApp.PostResource do
use JSONAPIPlug.Resource,
type: "post",
attributes: [
title: nil,
text: nil,
excerpt: [serialize: fn %Post{} = post, _conn -> String.slice(post.body, 0..5) end]
]
@impl JSONAPIPlug.Resource
def meta(%Post{} = post, _conn), do: %{slug: to_slug(post.title)}
end
To use the resource module in Phoenix, just call render and pass the data from your controller:
defmodule MyAppWeb.PostsController do
...
plug JSONAPIPlug.Plug, api: MyApp.API, resource: MyApp.PostResource
...
def create(%Conn{private: %{jsonapi_plug: jsonapi_plug}} = conn, params) do
post = ...create a post using jsonapi_plug parsed parameters...
render(conn, "create.json", %{data: post})
end
def index(%Conn{private: %{jsonapi_plug: jsonapi_plug}} = conn, _params) do
posts = ...load data using jsonapi_plug parsed parameters...
render(conn, "index.json", %{data: posts})
end
def show(%Conn{private: %{jsonapi_plug: jsonapi_plug} = conn, _params) do
post = ...load data using jsonapi_plug parsed parameters...
render(conn, "show.json", %{data: post})
end
def udate(%Conn{private: %{jsonapi_plug: jsonapi_plug}} = conn, params) do
post = ...update a post using jsonapi_plug parsed parameters...
render(conn, "update.json", %{data: post})
end
end
If you have a Plug
application, you can call JSONAPIPlug.Resource.render/5
to generate a JSONAPI.Document
with your data for the client. The structure is serializable to JSON with Jason
.
See the JSONAPIPlug.Plug
and JSONAPIPlug.Resource
modules documentation for more information.
Contributing
- This project was born as a fork of the jsonapi library but has since been completely rewritten and is now a completely different project.
- PRs for new features, bug fixes, documentation and tests are welcome
- If you are proposing a large feature or change, please open an issue for discussion