Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

JsonApiClient Build Docs

A JSON API Client for elixir.

NOTICE: This library is new and in active development. There could be backwards incompatible changes as the design shakes out. YMMV, PRs welcome.


This package can be installed by adding json_api_client to your list of dependencies in mix.exs:

def deps do
    {:json_api_client, "~> 3.0"}

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at


import JsonApiClient.Request

base_url = ""

# Fetch a resource by URL
{:ok, response} = fetch <> "/articles/123")

# build the request by composing helper functions
{:ok, response} = <> "/articles")
|> id("123")
|> fetch

# Fetch a list of resources
{:ok, response} = <> "/articles")
|> fields(articles: "title,topic", authors: "first-name,last-name,twitter")
|> include(:author)
|> sort(:id)
|> page(size: 10, number: 1)
|> filter(published: true)
|> params(custom1: 1, custom2: 2)
|> fetch

# Delete a resource
{:ok, response} = <> "/articles")
|> id("123")
|> delete

# Create a resource
new_article = %Resource{
  type: "articles",
  attributes: %{
    title: "JSON API paints my bikeshed!",
{:ok, %{status: 201, doc: %{data: article}}} = <> "/articles")
|> resource(new_article)
|> create

# Update a resource
{:ok, %{status: 200, doc: %{data: updated_article}}} = <> "/articles")
|> resource(%Resource{article | attributes: %{title: "New Title}})
|> update

Non-compliant servers

For the most part this library assumes that the server you're talking to implements the JSON:API spec correctly and treats deviations from that spec as exceptional (causing JsonApiClient.execute/1 to return an {:error, _} tuple for example). One exception to this rule is the case where a server sends back an invalid body (HTML or some non-json string) along with a 4** or 5** status code. In those cases the body will simply be ignored. See the docs for JsonApiClient.execute/1 for more details.

Helpers for common URI structures

The JSON:API specification doesn't provide any guidance on URI structure, but there is a common convention for REST apis to expose an endpoints with the following structure

# fetch a list of resources of a given type
GET /:type_name

# Create a resource of a given type
POST /:type_name

# Fetch/Update/Delete a resource by id
GET /:type_name/:id
PATCH /:type_name/:id
DELETE /:type_name/:id

When making requests to API endpoints that follow these conventions you can avoid having to build the full path yourself by adding JsonApiClient.Resource to the request.

# GET base_url <> "/articles/123"
{:ok, response} =
|> resource(%Resource{id: "123", type: "articles"})
|> fetch

# GET base_url <> "/articles"
{:ok, response} =
|> resource(%Resource{type: "articles"})
|> fetch

You can also build paths to nested resources by passing a Resource to path/2

# GET base_url <> "/articles/123/comments/456"
{:ok, response} =
|> path(%Resource{id: "123", type: "articles"})
|> resource(%Resource{id: "456", type: "comments"})
|> fetch

If the API your making requests which follows a different URI pattern you can pass a string to path/2 and it will be appended to the base url.


user agent suffix

Every request made carries a special User-Agent header that looks like: json_api_client/1.0.0/user_agent_suffix. Each client is expected to set its user_agent_suffix via:

config :json_api_client, user_agent_suffix: "yourSufix"


This library allows its users to specify a timeout for all its service calls by using a timeout setting. By default, the timeout is set to 500msecs.

config :json_api_client, timeout: 200


JsonApiClient is implemented using a middleware architecture. You can configure the middleware stack by setting middlewares to a list of {Module, opts} tuples where Module is a module that implements the JsonApiClient.Middleware behavior and opts is the options that will be passed as the last argument to the modules call function.

config :json_api_client,
  middlewares: [
    {JsonApiClient.Middleware.DocumentParser, nil}
    {JsonApiClient.Middleware.HTTPClient, nil},

If you don't configure a value for middlewares you'll get a stack equivalent to the one configured in the preceding example.

included middlewre

The following middleware ships with JsonApiClient:

  • JsonApiClient.Middleware.Fuse
  • JsonApiClient.Middleware.StatsTracker

Please refer to the module documentation for each middleware for information


JSON API Client Library For Elixir







No packages published