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).
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 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 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 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 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.
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.
API of request is somewhat mixture of jQuery.ajax (Javascript) and requests.request (Python).
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.
Integer HTTP response code (e.g., 200).
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 |
Response parsed by the given parser.
Error thrown during request. It takes the form of (ERROR-SYMBOL . DATA), which can be re-raised (signaled) by (signal ERROR-SYMBOL DATA).
A symbol representing the status of request (not HTTP response code). One of success/error/timeout/abort/parse-error.
Final URL location of response.
Return t when the request is finished or aborted.
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.
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
Return cookie string (like document.cookie).
Example:
(request-cookie-string "127.0.0.1" "/") ; => "key=value; key2=value2"
Return cookies as an alist.
Example:
(request-cookie-alist "127.0.0.1" "/") ; => (("key" . "value") ...)
deferred.el is a concise way to write callback chain. You can use require-deferred to do requests with deferred.el.
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 variables are for users. Libraries using request.el must not modify these variables.
Directory to store data related to request.el.
Executable for curl command.
Backend to be used for HTTP request. Automatically set to curl if curl command is found.
Default request timeout in second. nil means no timeout.
Logging level for request. One of error/warn/info/verbose/debug. -1 means no logging.
Logging level for request. See request-log-level.