HTTP adapter helper module.
Facilitates HTTP requests using the configured adapter and normalizes responses.
This module also specifies the behavior of an HTTP adapter. The behavior basically aligns with
Req's API, so alternative implementations need to come with batteries included
(e.g., JSON parsing) and sensible defaults provided. All request parameters and adapter
configuration options are passed as a single keyword list to the request/1 function.
Setting an adapter and the adapter default configuration
Default options for the adapter are set in the http_impl tuple when injecting the
implementation into a DSpace.API.t/0 structure by passing a list of options:
%DSpace.API{
endpoint: "https://example.com/server",
http_impl: {MyApp.HTTPAdapter, [pool_timeout: 5000]}
}Options passed to individual requests are merged with these defaults, with the former taking precedence.
Request options
An adapter implementation supports the following options:
:url- request URL:method- verb as atom (:get,:post, etc.). If not set, adapter defaults toGETrequest:headers- request headers:params- if set, appends parameters to the request query string:json- if map data, adapter will encode it, set it as body, and set appropriate content-type header:form- if map data, adapter will URL-encode it, set it as body, and set appropriate content-type header:form_multipart- if map data, adapter will encode as multipart/form-data, set it as body, and set appropriate content-type header:body- request body:decode_body- iffalse, the adapter will not decode the response body
Response
An adapter implementation returns the response as a DSpace.API.HTTP.Response.t/0 with the
fields:
:status- HTTP status code as integer:headers- HTTP response headers as a map:body- response body, already decoded into a map
Summary
Callbacks
Executes an HTTP request and returns a response or an error.
Types
@type options() :: [ url: URI.t() | binary(), method: :get | :head | :post | :put | :patch | :delete, headers: %{optional(binary() | atom()) => [binary()]}, params: keyword(), json: map() | nil, form: map() | nil, form_multipart: map() | nil, body: iodata() | Enumerable.t() | nil, decode_body: boolean() | nil ]
Options supported by HTTP adapters.
@type response() :: {:ok, DSpace.API.HTTP.Response.t()} | {:error, DSpace.API.HTTP.Error.t()}
Response format returned by HTTP adapters.