The HTTP wire module for terminusdb_ex.
TerminusDB.Client is the only module that issues HTTP requests. Every
higher-level API module (TerminusDB.Database, TerminusDB.Document, …)
composes a request and delegates here. Centralizing the wire logic keeps auth,
headers, JSON, telemetry, retries, and error mapping in one place.
Built on Req. Connection context is carried by an
immutable TerminusDB.Config struct.
Functions
request/4— returns{:ok, body}or{:error, TerminusDB.Error.t()}.request!/4— returns the body or raisesTerminusDB.Error.request_response/4— returns{:ok, Req.Response.t()}when the full response (headers, status, streamed body) is needed.
Options
In addition to the telemetry-only :area and :raw flags, request options are
forwarded to Req: :json (JSON body), :body (raw body), :params (query string),
:into (response streaming target), :form, :form_multipart, :decode_body.
Examples
# Using the Database API (preferred)
{:ok, body} = TerminusDB.Database.create(config, "mydb", label: "My DB")
# Using the raw client directly
{:ok, body} =
TerminusDB.Client.request(config, :post, "db/admin/mydb",
json: %{label: "My DB", comment: "demo", schema: true},
area: :database
)Summary
Functions
Performs an HTTP request and returns {:ok, decoded_body} or {:error, Error.t()}.
Performs an HTTP request and returns the decoded body, or raises TerminusDB.Error.
Performs an HTTP request and returns {:ok, Req.Response.t()} with the full
response (status, headers, body). Use this when you need headers or a streamed
body (:into).
Builds the organization/database resource segment for the given config and
options, resolving the organization from opts[:organization] or
config.organization. Raises TerminusDB.Error if no database is scoped.
Types
Functions
@spec request(TerminusDB.Config.t(), method(), String.t(), keyword()) :: {:ok, term()} | {:error, TerminusDB.Error.t()}
Performs an HTTP request and returns {:ok, decoded_body} or {:error, Error.t()}.
The body is auto-decoded by Req when the response is JSON (string keys). For
non-2xx responses, an TerminusDB.Error is built from the structured api:*
body when present, or a generic :http error otherwise.
Options
See the module documentation. :area sets the telemetry event area
(default :connection). :raw returns the full Req.Response.t() instead of
the body.
Examples
iex> config = TerminusDB.Config.new(
...> endpoint: "http://localhost:6363",
...> adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})} end
...> )
iex> {:ok, body} = TerminusDB.Client.request(config, :get, "ok")
iex> body["api:status"]
"api:success"@spec request!(TerminusDB.Config.t(), method(), String.t(), keyword()) :: term()
Performs an HTTP request and returns the decoded body, or raises TerminusDB.Error.
iex> config = TerminusDB.Config.new(
...> endpoint: "http://localhost:6363",
...> adapter: fn req ->
...> {req, Req.Response.new(status: 200, body: %{"api:status" => "api:success"})}
...> end
...> )
iex> TerminusDB.Client.request!(config, :get, "ok")
%{"api:status" => "api:success"}@spec request_response(TerminusDB.Config.t(), method(), String.t(), keyword()) :: {:ok, Req.Response.t()} | {:error, TerminusDB.Error.t()}
Performs an HTTP request and returns {:ok, Req.Response.t()} with the full
response (status, headers, body). Use this when you need headers or a streamed
body (:into).
Examples
iex> config = TerminusDB.Config.new(
...> endpoint: "http://localhost:6363",
...> adapter: fn req -> {req, Req.Response.new(status: 200, body: %{"ok" => true})} end
...> )
iex> {:ok, resp} = TerminusDB.Client.request_response(config, :get, "ok")
iex> resp.status
200@spec resource_path( TerminusDB.Config.t(), keyword() ) :: String.t()
Builds the organization/database resource segment for the given config and
options, resolving the organization from opts[:organization] or
config.organization. Raises TerminusDB.Error if no database is scoped.
iex> config = TerminusDB.Config.new(endpoint: "http://localhost:6363")
...> |> TerminusDB.Config.with_database("mydb")
iex> TerminusDB.Client.resource_path(config, [])
"admin/mydb"
iex> TerminusDB.Client.resource_path(config, organization: "acme")
"acme/mydb"