search

pashky / restclient.el

HTTP REST client tool for emacs
1.99k stars 167 forks source link

readme

restclient.el

This is a tool to manually explore and test HTTP REST webservices. Runs queries from a plain-text query sheet, displays results as a pretty-printed XML, JSON and even images.

Usage

You can easily install restclient using package.el from MELPA.

Alternatively, deploy restclient.el into your site-lisp as usual, then add (require 'restclient) to your Emacs start-up file.

Once installed, you can prepare a text file with queries.

restclient-mode is a major mode which does a bit of highlighting and supports a few additional keypresses:

The last two functions are implemented as restclient-outline-mode minor mode, which is activated by default via hook for major mode. Remove this hook using (remove-hook 'restclient-mode-hook 'restclient-outline-mode) if you don't wish to have this behaviour, or it clashes with any other binding for TAB like autocomplete.

Query file example:

# -*- restclient -*-
#
# Gets  all Github APIs, formats JSON, shows response status and headers underneath.
# Also sends a User-Agent header, because the Github API requires this.
#
GET https://api.github.com
User-Agent: Emacs Restclient

#
# XML is supported - highlight, pretty-print
#
GET http://www.redmine.org/issues.xml?limit=10

#
# It can even show an image!
#
GET http://upload.wikimedia.org/wikipedia/commons/6/63/Wikipedia-logo.png
#
# A bit of json GET, you can pass headers too
#
GET http://jira.atlassian.com/rest/api/latest/issue/JRA-9
User-Agent: Emacs24
Accept-Encoding: compress, gzip

#
# Post works too, entity just goes after an empty line. Same is for PUT.
#
POST https://jira.atlassian.com/rest/api/2/search
Content-Type: application/json

{
        "jql": "project = HCPUB",
        "startAt": 0,
        "maxResults": 15,
        "fields": [
                "summary",
                "status",
                "assignee"
        ]
}
#
# And delete, will return not-found error...
#
DELETE https://jira.atlassian.com/rest/api/2/version/20

# Set a variable to the value of your ip address using a jq expression
GET http://httpbin.org/ip
-> jq-set-var :my-ip .origin

Lines starting with # are considered comments AND also act as separators.

HTTPS and image display requires additional dll's on windows (libtls, libpng, libjpeg etc), which are not in the emacs distribution.

More examples can be found in the examples directory.

In-buffer variables

You declare a variable like this:

:myvar = the value

or like this:

:myvar := (some (artbitrary 'elisp)

In second form, the value of variable is evaluated as Emacs Lisp form immediately. Evaluation of variables is done from top to bottom. Only one one-line form for each variable is allowed, so use (progn ...) and some virtual line wrap mode if you need more. There's no way to reference earlier declared restclient variables, but you can always use setq to save state.

Variables can be multiline too:

:myvar = <<
Authorization: :my-auth
Content-Type: application/json
User-Agent: SomeApp/1.0
#

or

:myvar := <<
(some-long-elisp
    (code spanning many lines)
#

<< is used to mark a start of multiline value, the actual value is starting on the next line then. The end of such variable value is the same comment marker # and last end of line doesn't count, same is for request bodies.

After the var is declared, you can use it in the URL, the header values and the body.

# Some generic vars

:my-auth = 319854857345898457457
:my-headers = <<
Authorization: :my-auth
Content-Type: application/json
User-Agent: SomeApp/1.0
#

# Update a user's name

:user-id = 7
:the-name := (format "%s %s %d" 'Neo (md5 "The Chosen") (+ 100 1))

PUT http://localhost:4000/users/:user-id/
:my-headers

{ "name": ":the-name" }

Varaibles can also be set based on the body of a response using the per-request hooks

# set a variable :my-ip to the value of your ip address using elisp evaluated in the result buffer
GET http://httpbin.org/ip
-> run-hook (restclient-set-var ":my-ip" (cdr (assq 'origin (json-read))))

# same thing with jq if it's installed
GET http://httpbin.org/ip 
-> jq-set-var :my-ip .origin

# set a variable :my-var using a more complex jq expression (requires jq-mode)
GET https://httpbin.org/json
-> jq-set-var :my-var .slideshow.slides[0].title

# hooks come before the body on POST
POST http://httpbin.org/post
-> jq-set-var :test .json.test

{"test": "foo"}

File uploads

Restclient now allows to specify file path to use as a body, like this:

POST http://httpbin.org/post
Content-type: text/plain

< /etc/passwd

Caveats:

Customization

There are several variables available to customize restclient to your liking. Also, all font lock faces are now customizable in restclient-faces group too.

restclient-log-request

Default: t

Determines whether restclient logs to the *Messages* buffer.

If non-nil, restclient requests will be logged. If nil, they will not be.

restclient-same-buffer-response

Default: t

Re-use same buffer for responses or create a new one each time.

If non-nil, re-use the buffer named by rest-client-buffer-response-name for all requests.

If nil, generate a buffer name based on the request type and url, and increment it for subsequent requests.

For example, GET http://example.org would produce the following buffer names on 3 subsequent calls:

restclient-same-buffer-response-name

Default: *HTTP Response*

Name for response buffer to be used when restclient-same-buffer-response is true.

restclient-inhibit-cookies

Default: nil

Inhibit restclient from sending cookies implicitly.

restclient-response-size-threshold

Default: 100000

Size of the response buffer restclient can display without huge performance dropdown. If response buffer will be more than that, only bare major mode will be used to display it. Set to nil to disable threshold completely.

Known issues

History

Related 3rd party packages

License

Public domain, do whatever you want.

Author

Pavel Kurnosov pashky@gmail.com