README.org

• BQN HTTP library

FFI bindings to [[https://curl.se/libcurl/][libcurl]] for [[https://mlochbaum.github.io/BQN/][BQN]]. Requires CBQN >= 0.12.

** Configuration

If =libcurl.so= isn't automatically found, set the location manually in [[./config.bqn][config.bqn]].

** Usage

*** Simple API

Only GET and POST requests are implemented at this time.

#+begin_src bqn ⟨Get,Post⟩←•Import"curl.bqn" #+end_src

Simple GET requests: #+begin_src bqn r←Get"https://httpbin.org/get" #+end_src

You can pass headers as a left argument: #+begin_src bqn r←⟨"Content-Type: application/json"⟩Get"https://httpbin.org/get" #+end_src

Arguments, port number, etc, can be included in the URL.

For POST requests, pass data as an additional string parameter. It will not be converted or encoded in any way. #+begin_src bqn r←⟨"Content-Type: application/json"⟩Post"https://httpbin.org/post"‿"{""key"": ""value""}" #+end_src

*** Response objects

The response object is a namespace with the following elements:

• code: the response code.
• headers: the response headers as a single string, separated by newlines.
• content: the response content, as raw bytes.
• time: the time the request took, in seconds.
• redirectCount: the number of redirects.

If your endpoint returns text, you can use FromBytes from [[https://github.com/mlochbaum/bqn-libs/blob/master/strings.bqn][bqn-libs/strings.bqn]] to decode UTF-8.

*** Advanced API

For more fine-grained control on request parameters, you can use the advanced API, which closely mirrors the libcurl API structure.

A session object is created with OpenSession, and can be reused to speed up successive requests by reusing an existing connection.

Create a request by modifying the session object. Each of the functions take the session as their right argument, and configuration data as their left argument. They modify the session in-place, but also return it so that they can be chained easily.

• url SetURL session: the request URL.
• headers SetHeaders session: the request headers, as a list of strings.
• SetVerbose session: log verbose request data to standard output.
• n SetTimeout session and n SetTimeoutms timeout: the request timeout, in seconds or in milliseconds.
• data SetData session: use a POST request and set the data to send, as a string.

Finally, perform the actual request with Perform, returning the response object as above.

The session object can then be reused for subsequent requests, modifying request parameters as needed. It can be reset to its default configuration using ResetSession, while preserving open connections and caches.

A session is terminated, and its memory freed, with CloseSession.

Full example: #+begin_src bqn ⟨ OpenSession,CloseSession, SetURL,SetHeaders,SetTimeoutms, Perform, ⟩←•Import"curl.bqn"

session←⟨"User-Agent: myapp"⟩SetHeaders OpenSession @ r1←Perform "https://httpbin.org/status/418"SetURL session •Show r1.code r2←Perform 500 SetTimeoutms "https://httpbin.org/ip"SetURL session •Out r2.content

CloseSession session #+end_src

** Running tests

Run a local [[https://httpbin.org/][httpbin.org]] instance with Docker: #+begin_src sh docker run -p 8080:80 kennethreitz/httpbin #+end_src

The tests can be run with =bqn tests.bqn=.