Request.el manual

Note

Entire manual is generated from docstrings. To quickly check what function/variable does, use <f1> f or <f1> v, (or C-h instead of <f1> if you don’t rebind it).

API

function (request url &rest settings)

Send request to URL.

Request.el has a single entry point. It is request.

Keyword argument Explanation
TYPE (string) type of request to make: POST/GET/PUT/DELETE
PARAMS (alist) set ”?key=val” part in URL
DATA (string/alist) data to be sent to the server
FILES (alist) files to be sent to the server (see below)
PARSER (symbol) a function that reads current buffer and return data
HEADERS (alist) additional headers to send with the request
SUCCESS (function) called on success
ERROR (function) called on error
COMPLETE (function) called on both success and error
TIMEOUT (number) timeout in second
STATUS-CODE (alist) map status code (int) to callback
SYNC (bool) If t, wait until request is done. Default is nil.
  • Callback functions

Callback functions STATUS, ERROR, COMPLETE and cdrs in element of the alist STATUS-CODE take same keyword arguments listed below. For forward compatibility, these functions must ignore unused keyword arguments (i.e., it’s better to use &allow-other-keys [1]).:

(CALLBACK                      ; SUCCESS/ERROR/COMPLETE/STATUS-CODE
 :data          data           ; whatever PARSER function returns, or nil
 :error-thrown  error-thrown   ; (ERROR-SYMBOL . DATA), or nil
 :symbol-status symbol-status  ; success/error/timeout/abort/parse-error
 :response      response       ; request-response object
 ...)
[1]&allow-other-keys is a special “markers” available in macros in the CL library for function definition such as cl-defun and cl-function. Without this marker, you need to specify all arguments to be passed. This becomes problem when request.el adds new arguments when calling callback functions. If you use &allow-other-keys (or manually ignore other arguments), your code is free from this problem. See info node (cl) Argument Lists for more information.

Arguments data, error-thrown, symbol-status can be accessed by request-response-data, request-response-error-thrown, request-response-symbol-status accessors, i.e.:

(request-response-data RESPONSE)  ; same as data

Response object holds other information which can be accessed by the following accessors: request-response-status-code, request-response-url and request-response-settings

  • STATUS-CODE callback

STATUS-CODE is an alist of the following format:

((N-1 . CALLBACK-1)
 (N-2 . CALLBACK-2)
 ...)

Here, N-1, N-2,... are integer status codes such as 200.

  • FILES

FILES is an alist of the following format:

((NAME-1 . FILE-1)
 (NAME-2 . FILE-2)
 ...)

where FILE-N is a list of the form:

(FILENAME &key PATH BUFFER STRING MIME-TYPE)

FILE-N can also be a string (path to the file) or a buffer object. In that case, FILENAME is set to the file name or buffer name.

Example FILES argument:

`(("passwd"   . "/etc/passwd")                ; filename = passwd
  ("scratch"  . ,(get-buffer "*scratch*"))    ; filename = *scratch*
  ("passwd2"  . ("password.txt" :file "/etc/passwd"))
  ("scratch2" . ("scratch.txt"  :buffer ,(get-buffer "*scratch*")))
  ("data"     . ("data.csv"     :data "1,2,3\n4,5,6\n")))

Note

FILES is implemented only for curl backend for now. As furl.el supports multipart POST, it should be possible to support FILES in pure elisp by making furl.el another backend. Contributions are welcome.

  • PARSER function

PARSER function takes no argument and it is executed in the buffer with HTTP response body. The current position in the HTTP response buffer is at the beginning of the buffer. As the HTTP header is stripped off, the cursor is actually at the beginning of the response body. So, for example, you can pass json-read to parse JSON object in the buffer. To fetch whole response as a string, pass buffer-string.

When using json-read, it is useful to know that the returned type can be modified by json-object-type, json-array-type, json-key-type, json-false and json-null. See docstring of each function for what it does. For example, to convert JSON objects to plist instead of alist, wrap json-read by lambda like this.:

(request
 "http://..."
 :parser (lambda ()
           (let ((json-object-type 'plist))
             (json-read)))
 ...)

This is analogous to the dataType argument of jQuery.ajax. Only this function can access to the process buffer, which is killed immediately after the execution of this function.

  • SYNC

Synchronous request is functional, but please don’t use it other than testing or debugging. Emacs users have better things to do rather than waiting for HTTP request. If you want a better way to write callback chains, use request-deferred.

If you can’t avoid using it (e.g., you are inside of some hook which must return some value), make sure to set TIMEOUT to relatively small value.

Due to limitation of url-retrieve-synchronously, response slots request-response-error-thrown, request-response-history and request-response-url are unknown (always nil) when using synchronous request with url-retrieve backend.

  • Note

API of request is somewhat mixture of jQuery.ajax (Javascript) and requests.request (Python).

function (request-abort response)

Abort request for RESPONSE (the object returned by request). Note that this function invoke ERROR and COMPLETE callbacks. Callbacks may not be called immediately but called later when associated process is exited.

Response object

function (request-response-status-code cl-x)

Integer HTTP response code (e.g., 200).

function (request-response-history cl-x)

Redirection history (a list of response object). The first element is the oldest redirection.

You can use restricted portion of functions for the response objects in the history slot. It also depends on backend. Here is the table showing what functions you can use for the response objects in the history slot.

Slots Backends
curl url-retrieve
request-response-url yes yes
request-response-header yes no
other functions no no
function (request-response-data cl-x)

Response parsed by the given parser.

function (request-response-error-thrown cl-x)

Error thrown during request. It takes the form of (ERROR-SYMBOL . DATA), which can be re-raised (signaled) by (signal ERROR-SYMBOL DATA).

function (request-response-symbol-status cl-x)

A symbol representing the status of request (not HTTP response code). One of success/error/timeout/abort/parse-error.

function (request-response-url cl-x)

Final URL location of response.

function (request-response-done-p cl-x)

Return t when the request is finished or aborted.

function (request-response-settings cl-x)

Keyword arguments passed to request function. Some arguments such as HEADERS is changed to the one actually passed to the backend. Also, it has additional keywords such as URL which is the requested URL.

function (request-response-header response field-name)

Fetch the values of RESPONSE header field named FIELD-NAME.

It returns comma separated values when the header has multiple field with the same name, as RFC 2616 specifies.

Examples:

(request-response-header response
                         "content-type") ; => "text/html; charset=utf-8"
(request-response-header response
                         "unknown-field") ; => nil

Deferred

deferred.el is a concise way to write callback chain. You can use require-deferred to do requests with deferred.el.

function (request-deferred url &rest args)

Send a request and return deferred object associated with it.

Following deferred callback takes a response object regardless of the response result. To make sure no error occurs during the request, check request-response-error-thrown.

Arguments are the same as request, but COMPLETE callback cannot be used as it is used for starting deferred callback chain.

Example:

(require 'request-deferred)

(deferred:$
  (request-deferred "http://httpbin.org/get" :parser 'json-read)
  (deferred:nextc it
    (lambda (response)
      (message "Got: %S" (request-response-data response)))))

Configuration

Configuration variables are for users. Libraries using request.el must not modify these variables.

variable (request-storage-directory "~/.emacs.d/request")

Directory to store data related to request.el.

variable (request-curl "curl")

Executable for curl command.

variable (request-backend 'curl)

Backend to be used for HTTP request. Automatically set to curl if curl command is found.

variable (request-timeout nil)

Default request timeout in second. nil means no timeout.

variable (request-log-level '-1)

Logging level for request. One of error/warn/info/verbose/debug. -1 means no logging.

variable (request-message-level 'warn)

Logging level for request. See request-log-level.