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
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.
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.
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 toJsonrpc.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/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>}