Jsonrpc (finch_jsonrpc v0.1.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 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! 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 can be used to make a JSON-RPC request, either single or a batch request.

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

Link to this function

call(request, options \\ [])

View Source

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()}

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.

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

Link to this function

call!(request, options \\ [])

View Source

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.

Link to this function

call_raw(request, options \\ [])

View Source

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.

  1. A single request is made when the request is a single Jsonrpc.Request struct
  2. 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}

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>}