API.md

Table of contents

• babashka.http-client
  • ->Authenticator - Constructs a java.net.Authenticator.
  • ->CookieHandler - Constructs a java.net.CookieHandler using java.net.CookieManager.
  • ->Executor - Constructs a java.util.concurrent.Executor.
  • ->ProxySelector - Constructs a java.net.ProxySelector.
  • ->SSLContext - Constructs a javax.net.ssl.SSLContext.
  • ->SSLParameters - Constructs a javax.net.ssl.SSLParameters.
  • client - Construct a custom client.
  • default-client-opts - Options used to create the (implicit) default client.
  • delete - Convenience wrapper for request with method :delete.
  • get - Convenience wrapper for request with method :get.
  • head - Convenience wrapper for request with method :head.
  • patch - Convenience wrapper for request with method :patch.
  • post - Convenience wrapper for request with method :post.
  • put - Convenience wrapper for request with method :put.
  • request - Perform request.
• babashka.http-client.interceptors
  • accept-header - Request: adds :accept header.
  • basic-auth - Request: adds :authorization header based on :basic-auth (a map of :user and :pass) in request.
  • construct-uri - Request: construct uri from map.
  • decode-body - Response: based on the value of :as in request, decodes as :string, :stream or :bytes.
  • decompress-body - Response: decompresses body based on "content-encoding" header.
  • default-interceptors - Default interceptor chain.
  • form-params - Request: encodes :form-params map and adds :body.
  • multipart - Adds appropriate body and header if making a multipart request.
  • oauth-token - Request: adds :authorization header based on :oauth-token (a string token) in request.
  • query-params - Request: encodes :query-params map and appends to :uri.
  • throw-on-exceptional-status-code - Response: throw on exceptional status codes.
  • unexceptional-statuses
  • uri-with-query - We can't use the URI constructor because it encodes all arguments for us.
• babashka.http-client.websocket - Code is very much based on hato's websocket code.
  • abort! - Closes this WebSocket's input and output abruptly.
  • close! - Initiates an orderly closure of this WebSocket's output by sending a Close message with the given status code and the reason.
  • ping! - Sends a Ping message with bytes from the given buffer.
  • pong! - Sends a Pong message with bytes from the given buffer.
  • send! - Sends a message to the WebSocket.
  • websocket - Builds java.net.http.Websocket client.

---

babashka.http-client

->Authenticator

(->Authenticator opts)

Constructs a java.net.Authenticator.

Options:

• :user - the username
• :pass - the password

_Source

->CookieHandler

(->CookieHandler opts)

Constructs a java.net.CookieHandler using java.net.CookieManager.

Options:

* `:store` - an optional `java.net.CookieStore` implementation
* `:policy` - a `java.net.CookiePolicy` or one of `:accept-all`, `:accept-none`, `:original-server`

_Source

->Executor

(->Executor opts)

Constructs a java.util.concurrent.Executor.

Options:

• :threads - constructs a ThreadPoolExecutor with the specified number of threads

_Source

->ProxySelector

(->ProxySelector opts)

Constructs a java.net.ProxySelector. Options:

• :host - string
• :port - long

_Source

->SSLContext

(->SSLContext opts)

Constructs a javax.net.ssl.SSLContext.

Options:

• :key-store - a file, URI or URL or anything else that is compatible with io/input-stream, e.g. (io/resource somepath.p12)
• :key-store-pass - the password for the keystore
• :key-store-type - the type of keystore to create [note: not the type of the file] (default: pkcs12)
• :trust-store - a file, URI or URL or anything else that is compatible with io/input-stream, e.g. (io/resource somepath.p12)
• :trust-store-pass - the password for the trust store
• :trust-store-type - the type of trust store to create [note: not the type of the file] (default: pkcs12)
• :insecure - if true, an insecure trust manager accepting all server certificates will be configured.

Note that :keystore and :truststore can be set using the javax.net.ssl.keyStore and javax.net.ssl.trustStore System properties globally.

_Source

->SSLParameters

(->SSLParameters opts)

Constructs a javax.net.ssl.SSLParameters.

Options:

• :ciphers - a list of cipher suite names
• :protocols - a list of protocol names

_Source

client

(client opts)

Construct a custom client. To get the same behavior as the (implicit) default client, pass default-client-opts.

Options:

• :follow-redirects - :never, :always or :normal
• :connect-timeout - connection timeout in milliseconds.
• :request - default request options which will be used in requests made with this client.
• :executor - a java.util.concurrent.Executor or a map of options, see docstring of ->Executor
• :ssl-context - a javax.net.ssl.SSLContext or a map of options, see docstring of ->SSLContext.
• :ssl-parameters - a javax.net.ssl.SSLParameters' or a map of options, see docstring of ->SSLParameters`.
• :proxy - a java.net.ProxySelector or a map of options, see docstring of ->ProxySelector.
• :authenticator - a java.net.Authenticator or a map of options, see docstring of ->Authenticator.
• :cookie-handler - a java.net.CookieHandler or a map of options, see docstring of ->CookieHandler.
• :version - the HTTP version: :http1.1 or :http2 (default: :http2).
• :priority - priority for HTTP2 requests, integer between 1-256 inclusive.

Returns map with:

• :client - a java.net.http.HttpClient.

The map can be passed to request via the :client key.

_Source

default-client-opts

Options used to create the (implicit) default client.

_Source

delete

(delete uri)
(delete uri opts)

Convenience wrapper for request with method :delete

_Source

get

(get uri)
(get uri opts)

Convenience wrapper for request with method :get

_Source

head

(head uri)
(head uri opts)

Convenience wrapper for request with method :head

_Source

patch

(patch url)
(patch url opts)

Convenience wrapper for request with method :patch

_Source

post

(post uri)
(post uri opts)

Convenience wrapper for request with method :post

_Source

put

(put url)
(put url opts)

Convenience wrapper for request with method :put

_Source

request

(request opts)

Perform request. Returns map with at least :body, :status

Options:

• :uri - the uri to request (required). May be a string or map of :scheme (required), :host (required), :port, :path and :query
• :headers - a map of headers
• :method - the request method: :get, :post, :head, :delete, :patch or :put
• :interceptors - custom interceptor chain
• :client - a client as produced by client or a clojure function. If not provided a default client will be used. When providing :client with a a clojure function, it will be called with the Clojure representation of the request which can be useful for testing.
• :query-params - a map of query params. The values can be a list to send multiple params with the same key.
• :form-params - a map of form params to send in the request body.
• :body - a file, inputstream or string to send as the request body.
• :basic-auth - a sequence of user password or map with :user :pass used for basic auth.
• :oauth-token - a string token used for bearer auth.
• :async - perform request asynchronously. The response will be a CompletableFuture of the response map.
• :async-then - a function that is called on the async result if successful
• :async-catch - a function that is called on the async result if exceptional
• :timeout - request timeout in milliseconds
• :throw - throw on exceptional status codes, all other than #{200 201 202 203 204 205 206 207 300 301 302 303 304 307}
• :version - the HTTP version: :http1.1 or :http2 (default: :http2).

_Source

---

babashka.http-client.interceptors

accept-header

Request: adds :accept header. Only supported value is :json.

_Source

basic-auth

Request: adds :authorization header based on :basic-auth (a map of :user and :pass) in request.

_Source

construct-uri

Request: construct uri from map

_Source

decode-body

Response: based on the value of :as in request, decodes as :string, :stream or :bytes. Defaults to :string.

_Source

decompress-body

Response: decompresses body based on "content-encoding" header. Valid values: gzip and deflate.

_Source

default-interceptors

Default interceptor chain. Interceptors are called in order for request and in reverse order for response.

_Source

form-params

Request: encodes :form-params map and adds :body.

_Source

multipart

Adds appropriate body and header if making a multipart request.

_Source

oauth-token

Request: adds :authorization header based on :oauth-token (a string token) in request.

_Source

query-params

Request: encodes :query-params map and appends to :uri.

_Source

throw-on-exceptional-status-code

Response: throw on exceptional status codes

_Source

unexceptional-statuses

_Source

uri-with-query

(uri-with-query uri new-query)

We can't use the URI constructor because it encodes all arguments for us. See https://stackoverflow.com/a/77971448/6264

_Source

---

babashka.http-client.websocket

Code is very much based on hato's websocket code. Credits to @gnarroway!

abort!

(abort! ws)

Closes this WebSocket's input and output abruptly.

_Source

close!

(close! ws)
(close! ws status-code reason)

Initiates an orderly closure of this WebSocket's output by sending a Close message with the given status code and the reason.

_Source

ping!

(ping! ws data)

Sends a Ping message with bytes from the given buffer.

_Source

pong!

(pong! ws data)

Sends a Pong message with bytes from the given buffer.

_Source

send!

(send! ws data)
(send! ws data opts)

Sends a message to the WebSocket. data can be a CharSequence (e.g. string), byte array or ByteBuffer

Options:

• :last: this is the last message, defaults to true

_Source

websocket

(websocket {:keys [client], :as opts})

Builds java.net.http.Websocket client.

• :uri - the uri to request (required). May be a string or map of :scheme (required), :host (required), :port, :path and :query
• :headers - a map of headers for the initial handshake`
• :client - a client as produced by client. If not provided a default client will be used.
• :connect-timeout Sets a timeout for establishing a WebSocket connection (in millis).
• :subprotocols - sets a request for the given subprotocols.
• :async - return CompleteableFuture of websocket

Callbacks options:

• :on-open - [ws], called when a WebSocket has been connected.
• :on-message - [ws data last] A textual/binary data has been received.
• :on-ping - [ws data] A Ping message has been received.
• :on-pong - [ws data] A Pong message has been received.
• :on-close - [ws status reason] Receives a Close message indicating the WebSocket's input has been closed.
• :on-error - [ws err] An error has occurred.

_Source