Mark McGranaghan

Introducing clj-http, a Clojure HTTP Client

August 16 2010

clj-http is a new Clojure HTTP client library inspired by Ring and designed for simplicity, robustness, extensibility, and testability.

For basic use cases, it provides a high-level interface:

(require '[clj-http.client :as client])

(client/get "")
=> {:status 200
    :headers {"date" "Sun, 01 Aug 2010 07:03:49 GMT"
              "cache-control" "private, max-age=0, must-revalidate"
              "content-type" "text/html; charset=utf-8"
    :body "GET"}

This interface accepts various options. For example:

(:body (client/post ""
         {:body "body data" :content-type "text/plain"}))
=> "POST with a 9 byte payload,
    content type text/plain; charset=UTF-8"

The library also provides a more general interface for use in building domain-specific client libraries:

(defn api-request [method path body]
      {:method method
       :url (str "" path)
       :content-type "text/plain"
       :body body})))

(api-request :post "/resource" "data")
=> "POST with a 4 byte payload,
    content type text/plain; charset=UTF-8"

clj-http uses a similar architecture to the Ring Clojure HTTP server library. It defines a simple interface abstracting the HTTP request/response cycle and implements all additional features through this interface. For example, this is how clj-http.client/request is defined:

(def request
  (-> #'core/request

clj-http is still in the early stages of development, but is ready for testing by interested Clojure users. Give it a shot by including it in your applications with:

  [[clj-http "0.1.1"] ...]

You can learn more about the library on its project page. I look forward to your hearing your thoughts, suggestions, and criticisms. Let me know what you think in the comments below or on the Clojure mailing list.

If you are interested in Clojure HTTP libraries in general, you should also check out clojure-http-client, clj-apache-http, and ahc-clj.

Thanks to the Bay Area Clojure Users Group for the initial Ring-style-HTTP-client suggestion, to Daniel Janus for another nudge in this direction, to Adam Wiggins for the inspiration of rest-client and the site, and to Bradford Cross for design and implementation collaboration.