Jsonrpc (jsonrpc v0.2.0) View Source

Jsonrpc is a simple JSON-RPC HTTP client built on Finch It implements the JSON-RPC 2.0 specification

Starting under a supervisor

Jsonrpc is preferably started under a Supervisor. See Jsonrpc.start_link/1 for more information:

defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    children = [
      %{
        id: Jsonrpc,
        start: {Jsonrpc, :start_link, [name: :example]}
      }
    ]

    # See https://hexdocs.pm/elixir/Supervisor.html
    # for other strategies and supported options
    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

Making a single request

Jsonrpc requests can be created using Jsonrpc.Request.new/1 and send using Jsonrpc.call/2

Jsonrpc.Request.new(method: "exampleMethod")
|> Jsonrpc.call(name: :example, url: "https://finchjsonrpc.redmaner.com)

Making a batch request

Jsonrpc supports batch requests. When the request is a list of requests, a batch RPC call is made automatically. See Jsonrpc.Request.new/2 on how to make batch requests.

Jsonrpc.Request.new(method: "exampleMethod")
|> Jsonrpc.Request.new(method: "exampleMethodTwo")
|> Jsonrpc.call(name: :example, url: "https://finchjsonrpc.redmaner.com)

Link to this section Summary

Functions

call(request, options \\ [])

call is the same as call_raw but instead of returning the Jsonrpc.Response struct it will unwrap the struct for you. It will return {:ok, result} when the call was successful or {:error, error} when the call failed where error will be a Jsonrpc.Error struct.

call!(request, options \\ [])

call! is the same as call/2 only it unwraps the result even further. It will directly unwrap the result if the call was successful or will raise an error if the call was unsuccessful.

call_raw(request, options \\ [])

call_raw can be used to make a JSON-RPC request, either single or a batch request.

start_link(opts)

start_link/1 is used to start Jsonrpc under a supervisor. A required option is name, which is used to communicate with Finch. For more options see Finch.start_link/1.

Link to this section Functions

call(request, options \\ [])

Specs

call(request :: Request.t() | [Request.t()], options :: list()) ::
  {:ok, responses :: [Jsonrpc.Response.t()]}
  | {:ok, response :: term()}
  | {:error, responses :: [Jsonrpc.Response.t()]}
  | {:error, response :: term()}
  | {:error, reason :: term()}

The response for batch requests is the same as for call_raw/2. Each response should be unwrapped manually for batch requests.

call!(request, options \\ [])

call! is the same as call/2 only it unwraps the result even further. It will directly unwrap the result if the call was successful or will raise an error if the call was unsuccessful.

It a batch request is made the entire list of raw responses is returned if all requests succeeded or an error is raised when one or more requests failed.

call_raw(request, options \\ [])

Specs

call_raw(request :: Request.t() | [Request.t()], options :: list()) ::
  {:ok, responses :: [Jsonrpc.Response.t()]}
  | {:ok, response :: Jsonrpc.Response.t()}
  | {:error, responses :: [Jsonrpc.Response.t()]}
  | {:error, response :: Jsonrpc.Response.t()}
  | {:error, reason :: term()}

call_raw can be used to make a JSON-RPC request, either single or a batch request.

A single request is made when the request is a single Jsonrpc.Request struct
A batch request is made when teh request is a list of Jsonrpc.Request structs

call_raw takes an option list:

name: the name of the Finch client that was supplied to Jsonrpc.start_link/1 This keyword is required!
url: the url that must be used to make the request. This keyword is required!
headers: a set of headers. This is optional.

call_raw returns a raw Jsonrpc.Response struct. It is wrapped in {:ok, response} when result is not nil or {:error, response} when error is not nil. If the call was a batch request, the responses are wrapped in {:ok, responses} when ALL responses were successful. If one of the batch respones contains an error it is always wrapped in {:error, responses}

start_link(opts)

Specs

start_link(opts :: list()) :: :ignore | {:error, any()} | {:ok, pid()}

start_link/1 is used to start Jsonrpc under a supervisor. A required option is name, which is used to communicate with Finch. For more options see Finch.start_link/1.

Example:

iex(1)> Jsonrpc.start_link(name: :example)
{:ok, #PID<0.232.0>}