Request.el – Easy HTTP request for Emacs Lisp¶
- Documentation (at GitHub Pages)
- Repository (at GitHub)
- Issue tracker (at GitHub)
- Travis CI
What is it?¶
Request.el is a HTTP request library with multiple backends. It supports url.el which is shipped with Emacs and curl command line program. User can use curl when s/he has it, as curl is more reliable than url.el. Library author can use request.el to avoid imposing external dependencies such as curl to users while giving richer experience for users who have curl.
As request.el is implemented in extensible manner, it is possible to implement other backend such as wget. Also, if future version of Emacs support linking with libcurl, it is possible to implement a backend using it. Libraries using request.el automatically can use these backend without modifying their code.
Request.el also patches url.el dynamically, to fix bugs in url.el. See monkey patches for url.el for the bugs fixed by request.el.
Examples¶
GET:
(request
"http://httpbin.org/get"
:params '(("key" . "value") ("key2" . "value2"))
:parser 'json-read
:success (cl-function
(lambda (&key data &allow-other-keys)
(message "I sent: %S" (assoc-default 'args data)))))
POST:
(request
"http://httpbin.org/post"
:type "POST"
:data '(("key" . "value") ("key2" . "value2"))
;; :data "key=value&key2=value2" ; this is equivalent
:parser 'json-read
:success (cl-function
(lambda (&key data &allow-other-keys)
(message "I sent: %S" (assoc-default 'form data)))))
POST file (WARNING: it will send the contents of the current buffer!):
(request
"http://httpbin.org/post"
:type "POST"
:files `(("current buffer" . ,(current-buffer))
("data" . ("data.csv" :data "1,2,3\n4,5,6\n")))
:parser 'json-read
:success (cl-function
(lambda (&key data &allow-other-keys)
(message "I sent: %S" (assoc-default 'files data)))))
Rich callback dispatch (like jQuery.ajax):
(request
"http://httpbin.org/status/418" ; try other codes, for example:
;; "http://httpbin.org/status/200" ; success callback will be called.
;; "http://httpbin.org/status/400" ; you will see "Got 400."
:parser 'buffer-string
:success
(cl-function (lambda (&key data &allow-other-keys)
(when data
(with-current-buffer (get-buffer-create "*request demo*")
(erase-buffer)
(insert data)
(pop-to-buffer (current-buffer))))))
:error
(cl-function (lambda (&key error-thrown &allow-other-keys&rest _)
(message "Got error: %S" error-thrown)))
:complete (lambda (&rest _) (message "Finished!"))
:status-code '((400 . (lambda (&rest _) (message "Got 400.")))
(418 . (lambda (&rest _) (message "Got 418.")))))
Flexible PARSER option:
(request
"https://github.com/tkf/emacs-request/commits/master.atom"
;; Parse XML in response body:
:parser (lambda () (libxml-parse-xml-region (point) (point-max)))
:success (cl-function
(lambda (&key data &allow-other-keys)
;; Just don't look at this function....
(let ((get (lambda (node &rest names)
(if names
(apply get
(first (xml-get-children
node (car names)))
(cdr names))
(first (xml-node-children node))))))
(message "Latest commit: %s (by %s)"
(funcall get data 'entry 'title)
(funcall get data 'entry 'author 'name))))))
PUT JSON data:
(request
"http://httpbin.org/put"
:type "PUT"
:data (json-encode '(("key" . "value") ("key2" . "value2")))
:headers '(("Content-Type" . "application/json"))
:parser 'json-read
:success (cl-function
(lambda (&key data &allow-other-keys)
(message "I sent: %S" (assoc-default 'json data)))))
Compatibility / backends¶
Supported Emacs versions:
| Emacs version | Does request.el work? | Tested on Travis CI
|
|---|---|---|
| GNU Emacs 24.3-devel | yes (as of this writing) | yes |
| GNU Emacs 24.2 | yes | yes |
| GNU Emacs 24.1 | yes | no |
| GNU Emacs 23.4 | yes | no |
| GNU Emacs 23.3 | yes | yes |
| GNU Emacs 23.1 | yes (as of this writing) | no |
| GNU Emacs < 23 | ? | no |
Supported backends:
| Backends | Remarks | Multipart Form | Automatic Decompression |
|---|---|---|---|
| url.el | Included in Emacs | ||
| curl | Reliable | ✔ | ✔ |
Monkey patches for url.el¶
Patches for following bugs are applied when request.el is loaded. If the patch is not required for the Emacs version you are using, it will not be applied.
License¶
Request.el is free software under GPL v3. See COPYING file for details.