101 lines
3.1 KiB
Org Mode
101 lines
3.1 KiB
Org Mode
* BQN HTTP library
|
|
|
|
FFI bindings to [[https://curl.se/libcurl/][libcurl]] for [[https://mlochbaum.github.io/BQN/][BQN]].
|
|
|
|
** Configuration
|
|
|
|
Set the location of the =libcurl.so= library 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.
|
|
|
|
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=.
|