diff options
| -rw-r--r-- | README.md | 32 | ||||
| -rw-r--r-- | jurl/init.janet | 36 |
2 files changed, 59 insertions, 9 deletions
@@ -42,10 +42,32 @@ If you run into issues with building, please see the CONTRIBUTING document - cha ## Jurl `jurl` is a requests-style API, but more complete. + You can use the `jurl/request` function directly (see its documentation for more details), -or the pipeline high level API. +`slurp` and `spit` for very basic http requests, or the pipeline high level API. + +Here are examples of `slurp` and `spit`: +```janet +(slurp "https://pie.dev/get") +# => @"{\"args\": {} ..." + +(slurp "https://example.com/404") +# => (error 404) + +(slurp "https://example.com/nxdomain") +# => (error :error/...) + +(spit "https://pie.dev/post" "post body") +# => @"{... \"data\": \"post body\" ...}" + +(spit "https://pie.dev/post" `{"key": "value"}` :content-type :application/json) +# => @"{ ... \"json\": {\"key\": \"value\"} ...}" + +(spit "https://pie.dev/post" (slurp "https://pie.dev/get") :content-type :application/json) +# => ... +``` -Here are a few basic examples. +Here are a few basic examples of the pipeline API. ```janet # prepare and execute a GET to pie.dev/get ((http :get "https://pie.dev/get")) @@ -77,16 +99,16 @@ Here are a few basic examples. (def req (->> "https://pie.dev/post" (http :post) (body "my body") - (headers {:content-type "application/octet-stream"}))) + (headers {:content-type :application/octet-stream}))) # oops I want it to be application/json (def req2 (->> req - (headers {:content-type "application/json" + (headers {:content-type :application/json :custom-header "custom-value"}))) # you can still use the old prepared request (req) # => {:body ...} # actually, in the end, I want text/plain # note that custom-header is still set -(req2 {:headers {:content-type "text/plain"}}) +(req2 {:headers {:content-type :text/plain}}) # => {:body ...} ``` diff --git a/jurl/init.janet b/jurl/init.janet index 29c6cee..8cbbd01 100644 --- a/jurl/init.janet +++ b/jurl/init.janet @@ -8,6 +8,10 @@ (setdyn :doc ````Janet cURL: a convenient and complete http client for janet. + The fastest way to get started is using the `slurp` and `spit` functions. + `slurp` corresponds to an HTTP GET, and `spit` to an HTTP POST. + For extra details, see their documentation. + The medium-level API to build your own higher level one is available via the `*default-options*` var and the `request` function. @@ -396,7 +400,6 @@ [qs] {:query qs}) -# fast and convenient functions (defn- verify-slurpit [f &opt opts] (def out (f opts)) @@ -408,15 +411,40 @@ (out :body)) (defn slurp - [url &opt opts] + ```Performs an HTTP GET to `url`. + + It will throw an error in case the request doesn't succeed, + else return the request body. + A failed request is defined as a request that returns a curl error + or a non-2xx HTTP response code. + + Can also take the following named parameters: + * opts: Options to intelligently merge with the resulting query. + To see what can go into opts, see the docs for `request`. + ``` + [url &named opts] (verify-slurpit (http :get url) opts)) (defn spit - [url body &opt opts] + ```Performs an HTTP POST to `url` with the body `body`. + By default, uses the `text/plain` content type. + + It will throw an error in case the request doesn't succeed, + else return the request body. + A failed request is defined as a request that returns a curl error + or a non-2xx HTTP response code. + + Can also take the following named parameters: + * content-type: The content type to set. Defaults to `text/plain`. + * opts: Options to intelligently merge with the resulting query. + To see what can go into opts, see the docs for `request`. + ``` + [url body &named content-type opts] + (default content-type "text/plain") (verify-slurpit (->> url (http :post) - (body-plain body)) + (body-type body content-type)) opts)) |