Skip to content

API.md

Latest commit

 

History

History
463 lines (298 loc) · 22.2 KB

API.md

File metadata and controls

463 lines (298 loc) · 22.2 KB

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