vim-rest-console.txt

*vim-rest-console.txt* *vrc*  A plug-in to help work with RESTful services.

                    __     ______   ____  ~
                    \ \   / /  _ \ / ___| ~
                     \ \ / /| |_) | |     ~
                      \ V / |  _ <| |___  ~
                       \_/  |_| \_\\____| ~


VRC creates a vim-friendly console to interact with RESTful services.

==============================================================================
CONTENTS                                                         *VrcContents*

  1. Introduction.......................................... |VrcIntroduction|
  2. Features.................................................. |VrcFeatures|
  3. Installation.......................................... |VrcInstallation|
  4. Examples.................................................. |VrcExamples|
      4.1 Single VRC Buffer.............................. |VrcExSingleBuffer|
      4.2 Multiple VRC Buffers........................... |VrcExMultiBuffers|
  5. Usage........................................................ |VrcUsage|
      5.1 cUrl Options...................................... |VrcCurlOptions|
      5.2 Global Definitions.......................... |VrcGlobalDefinitions|
      5.3 Global Variable Declaration..................... |VrcGlobalVarDecl|
      5.4 Line-by-line Request Body.................... |VrcSplitRequestBody|
      5.5 Consecutive Request Verbs......................... |VrcConReqVerbs|
  6. Configuration........................................ |VrcConfiguration|
      vrc_allow_get_request_body................ |vrc_allow_get_request_body|
      vrc_auto_format_response_enabled.... |vrc_auto_format_response_enabled|
      vrc_auto_format_response_patterns...|vrc_auto_format_response_patterns|
      vrc_auto_format_uhex.............................|vrc_auto_format_uhex|
      vrc_curl_opts.......................................... |vrc_curl_opts|
      vrc_debug.................................................. |vrc_debug|
      vrc_elasticsearch_support.................. |vrc_elasticsearch_support|
      vrc_header_content_type...................... |vrc_header_content_type|
      vrc_horizontal_split.....   .................... |vrc_horizontal_split|
      vrc_keepalt.............................................. |vrc_keepalt|
      vrc_output_buffer_name........................ |vrc_output_buffer_name|
      vrc_response_default_content_type.. |vrc_response_default_content_type|
      vrc_set_default_mapping...................... |vrc_set_default_mapping|
      vrc_show_command.....................................|vrc_show_command|
      vrc_split_request_body........................ |vrc_split_request_body|
      vrc_syntax_highlight_response...........|vrc_syntax_highlight_response|
      vrc_trigger.............................................. |vrc_trigger|
  7. Tips 'n Tricks................................................. |VrcTnt|
      7.1 POST Data in Bulk................................. |VrcTntDataBulk|
      7.2 Syntax Highlighting.................................. |VrcTntStxHi|
  8. Contributors.......................................... |VrcContributors|
  9. License.................................................... |VrcLicense|

==============================================================================
                                                             *VrcIntroduction*
1. INTRODUCTION~

This plug-in is to help send requests to and display responses from RESTful
services in Vim. It's useful for working with REST services that use JSON to
exchange information between server and client such as Elasticsearch.

VRC can also be used as a cURL client for simple needs such as getting a
HTTP page response or posting to a form.

Requirements:
  * cURL
  * Vim 7.4 (might work with the older versions)

==============================================================================
                                                                 *VrcFeatures*
2. FEATURES~

* Execute REST request and display the response on a separate display buffer.
* Make changing/adjusting request body easy.
* Can have multiple REST request blocks per VRC buffer.
* Can have multiple VRC buffers where they all share the same output buffer or
  each can have its own output buffer.
* Particularly useful for working with REST services that require the request
  body to be sent in JSON such as Elasticsearch.
* Syntax highlighting.
* Supported verbs: GET, POST, PUT, HEAD, PATCH, OPTIONS, and TRACE.

==============================================================================
                                                             *VrcInstallation*
3. INSTALLATION~

To install using pathogen.vim
>
    cd ~/.vim/bundle
    git clone https://github.com/diepm/vim-rest-console.git
<
To install using Vundle

    " Add this line to .vimrc >
    Plugin 'diepm/vim-rest-console'
<
Other methods should work as well.

==============================================================================
                                                                 *VrcExamples*
4. EXAMPLES~

For more examples, check out

https://raw.githubusercontent.com/diepm/vim-rest-console/master/sample.rest

The following examples assume that an Elasticsearch service is running at
localhost. The pipe (|) indicates the current position of the cursor.

------------------------------------------------------------------------------
                                                           *VrcExSingleBuffer*
4.1 Single VRC Buffer~

  * From the command line, run a new Vim instance.
  * Set the buffer `filetype` to 'rest' by
>
      :set ft=rest
<
  * Type in
>
      http://localhost:9200
      GET /_cat/nodes?v|
<
  * Hit the trigger key (<C-j> by default).
  * A new vertically split buffer will be shown to display the output.
  * Change the request block to (or add another one)
>
      http://localhost:9200
      POST /testindex/testtype
      {
          "key": "new key",
          "value": "new value"|
      }
<
  * Hit the trigger key with the cursor placed anywhere within this request
    block.
  * The display buffer will be updated with the new response.

------------------------------------------------------------------------------
                                                           *VrcExMultiBuffers*
4.2 Multiple VRC Buffers~

This example continues the previous one.

  * Open a new VRC buffer in a new tab
>
      :tabe NewVrc.rest
<
  * Since the new buffer has the extension 'rest', the VRC plug-in is active
    for this one.

  * Set |vrc_output_buffer_name| of this buffer to '__NEW_VRC__'
>
      :let b:vrc_output_buffer_name = '__NEW_VRC__'
<
  * Type in a request block such as
>
      http://localhost:9200
      GET /testindex/_search?pretty|
<
  * Hit the trigger key.
  * A new display buffer will be created showing the response.
  * Go back to the VRC buffer of the previous example (previous tab).
  * Try to execute an existing request block.
  * The corresponding display buffer will be updated.

==============================================================================
                                                                    *VrcUsage*
5. USAGE~

This plug-in is activated when Vim opens a buffer of type 'rest'. This may be
a file with the extension 'rest' or a buffer with `filetype` explicitly set to
'rest' by
>
    :set ft=rest
<
A VRC buffer can have one or many REST request blocks. A "request block"
contains a "host," "optional cUrl options," "optional headers," "query," and
an "optional request body" (usually used by POST). A block is defined as
follows.
>
    # host
    http[s]://domain[:port]

    [optional cUrl options]

    [optional headers]

    # query
    POST /path/to/resource
    [optional request body]
<
A comment starts with '#' or '//' and must be on its own line. The following
is an example of a VRC buffer with multiple request blocks.
>
    # GETting from resource.
    http://example.com
    GET /path/to/resource?key=value

    # POSTing to an Elasticsearch service.
    http://example.com/elasticsearch

    // Specify optional headers.
    Content-Type: application/json; charset=utf-8

    POST /index/type?pretty
    {
        "key": "a key",
        "value": "a value"
    }

    # Submitting a form.
    https://example.net:8080

    Accept: */*
    Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
    Cache-Control: no-cache
    Connection: keep-alive
    Content-Type: application/x-www-form-urlencoded
    Cookie: userId=ac32:dfbe:8f1a:249c; sid=cfb48e3d98fcb1
    User-Agent: VRC

    POST /form
    var1=value of var1&
    var2=value of var2
<
When the trigger key is called (<C-j> by default), VRC processes the request
block that the cursor stays within. The response is displayed in a new
vertically split buffer. This output buffer is reused if it's already present.

By default, the display/output buffer is named '__REST_response__'. If there
are multiple VRC buffers, they all share the same display buffer. To have a
separate output display for each VRC buffer, |vrc_output_buffer_name| can be
set in the buffer scope.

------------------------------------------------------------------------------
                                                              *VrcCurlOptions*
5.1 cUrl Options~

A recent addition to VRC is the ability to specify cUrl options. These may be
specified by the VRC option |vrc_curl_opts| or declaring in the global section
of a REST buffer (more at |VrcGlobalDefinitions|) and request blocks.

All specified cUrl options are merged together when a cUrl command is built.
For the same keys (cUrl switch) specified at different scopes, the ones of the
request blocks overwrite the ones in the global section then overwrite the
ones defined by |vrc_curl_opts|.

For the deprecated VRC options, they can be replaced by cUrl options. For
example, assuming they have been defined as follows.
>
    let g:vrc_connect_timeout = 10
    let g:vrc_cookie_jar = '/path/to/cookie'
    let g:vrc_follow_redirects = 1
    let g:vrc_include_response_header = 1
    let g:vrc_max_time = 60
    let g:vrc_resolve_to_ipv4 = 1
    let g:vrc_ssl_secure = 1
<
Using cUrl options,
>
    let g:vrc_curl_opts = {
      \ '--connect-timeout' : 10,
      \ '-b': '/path/to/cookie',
      \ '-c': '/path/to/cookie',
      \ '-L': '',
      \ '-i': '',
      \ '--max-time': 60,
      \ '--ipv4': '',
      \ '-k': '',
    \}
<
------------------------------------------------------------------------------
                                                        *VrcGlobalDefinitions*
5.2 Global Definitions~

The global section is separated from the rest with two dashes `--` and may
include a default host, optional default cUrl options (buffer scope) and
optional default headers. These values are always included in each request.

Each request block has to start with either two dashes indicating it uses the
default host from the global section or any host only used by this block. If
a 'local host' is given, it's used instead of the one specified in the global
section. Additionally, a request block can specify extra cUrl options and
headers. Local headers are merged with and overwrite global headers.
>
    # Global definitions.
    // Default host.
    https://domain[:port]/...

    // Default (buffer scope) cUrl options.
    -L
    --connect-timeout 10

    // Default headers.
    Accept: application/json
    X-Header: Custom Data
    --

    # Request block that uses default values from the global section.
    --
    GET /some/query

    # Request block that specifies its own host and extra headers.
    // Local host.
    https://example.net:9200

    // Local cUrl opts.
    -k
    --ipv4
    // This cUrl option overwrites the one in the global section.
    --connect-timeout 30
    -b /path/to/cookie
    -c /path/to/cookie

    // Extra headers.
    Xtra-Header: Some Extra.
    // This header will overwrite the one in the global section.
    X-Header: New Data

    POST /service
    var1=value
<
------------------------------------------------------------------------------
                                                            *VrcGlobalVarDecl*
5.3 Global Variable Declaration~

VRC now supports variable declarations in the global scope. These variables
then can be used in the query paths. Notice: values are not url-encoded.
>
    # Global scope.
    http://host

    // Variable declarations (value passed as is).
    city = Some%20City
    zip = 12345
    --
    # End global scope.

    --
    GET /city/:city

    --
    GET /city/:city/zip/:zip
<
------------------------------------------------------------------------------
                                                         *VrcSplitRequestBody*
5.4 Line-by-line Request Body~

Since version 2.3.0, the request body can be specified on a line-by-line
basis. It's useful for name-value pair services. Each line of the request
body is passed to cURL using `--data` or `--data-urlencode` depending on
the verb.

To enable,
>
    let g:vrc_split_request_body = 1
<
or
>
    let b:vrc_split_request_body = 1
<
Then the request body can be specified as
>
    #
    # The following params in the request body will be
    # sent using `--data-urlencode`
    #
    http://localhost
    Content-Type: text/html; charset=UTF-8
    GET /service
    var1=value1
    var2=value2
<
This option won't take effect for `GET` request if the option
|vrc_allow_get_request_body| is set.

------------------------------------------------------------------------------
                                                              *VrcConReqVerbs*
5.5 Consecutive Request Verbs

A request block may have consecutive request verbs. The output of each request
verb is appended to the output view.
>
    http://localhost:9200
    PUT /test
    GET /test
    DELETE /test
<
==============================================================================
                                                            *VrcConfiguration*
6. CONFIGURATION~

VRC supports a few configurable variables. Each of them can have a global or
buffer scope (the latter takes priority). An option can be set in '.vimrc' for
the global scope by
>
    let g:option_name = value
<
or in Vim for the buffer scope by
>
    let b:option_name = value
<
------------------------------------------------------------------------------
*vrc_allow_get_request_body*

Allow GET request to have a request body or not. Default: 0.

If this option is set, `-X GET` is used and the request body is passed to
cURL as a whole using `--data`.

This option is useful for such services as Elasticsearch.
>
    #
    # With vrc_allow_get_request_body = 1
    #
    http://localhost:9200
    Content-Type: application/json

    GET /testindex/testtype/_search
    {
      "query": {
        "match": { "name": "FOO" }
      }
    }
<
Be careful that when this option is enabled, the request body is always sent
as a whole regardless of |vrc_split_request_body|.

------------------------------------------------------------------------------
*vrc_auto_format_response_enabled*

This option enables the automatic formatting of the response. It's enabled by
default. To disable:
>
    let g:vrc_auto_format_response_enabled = 0
<
If the response header is not present (i.e., no `-i` cUrl option), this option
depends on the option |vrc_response_default_content_type|.

------------------------------------------------------------------------------
*vrc_auto_format_response_patterns*

This option defines which external tools to use to auto-format the response
body according to the Content-Type.

The defaults are:
>
    let s:vrc_auto_format_response_patterns = {
      \ 'json': 'python -m json.tool',
      \ 'xml': 'xmllint --format -',
    \}
>
Adjust the list by defining the global or buffer variable, like so:
>
    let g:vrc_auto_format_response_patterns = {
      \ 'json': ''
      \ 'xml': 'tidy -xml -i -'
    \}
<
If the response header isn't present (i.e., no `-i` cUrl option), this option
depends on the option |vrc_response_default_content_type|.

------------------------------------------------------------------------------
*vrc_auto_format_uhex*

If set, VRC will try to transform all unicode `\uXXXX` instances in the
response to the corresponding symbols. It's turned of by default.

------------------------------------------------------------------------------
*vrc_body_preprocessor*

An external command to run using the request body as input, the output of
which will then be used as the body for the request. Default is an empty
string, which will not run any preprocessing.

Example using yaml2json to convert from yaml (easier to type) to JSON,
and then piping into jq minify that:
>
    let g:vrc_body_preprocessor = 'yaml2json | jq -c .'
<
------------------------------------------------------------------------------
*vrc_curl_opts*

A dictionary that contains the default cUrl options. Default: not exist.
>
    let g:vrc_curl_opts = {
      \ '-sS': '',               <-- options without value.
      \ '--connect-timeout: 10,  <-- single option.
      \ '-H': ['header1: value1', 'header2: value2'],  <-- multi-option.
    \}
<
------------------------------------------------------------------------------
*vrc_debug*

This option enables the debug mode by adding the '-v' option to the 'curl'
command and also `echom` the command to the Vim console. It's turned off by
default.

------------------------------------------------------------------------------
*vrc_elasticsearch_support*

If enabled, the data of Elasticsearch's `_bulk` API can also be specified
directly in the request block instead of indirectly via an external file.
It's off by default.

------------------------------------------------------------------------------
*vrc_header_content_type*

This option is to set the header content type of the request. It defaults to
'application/json'. To set a different default content type,
>
    let g:vrc_header_content_type = 'application/x-www-form-urlencoded'
<
It can also be set in the buffer scope by
>
    let b:vrc_header_content_type = 'application/json; charset=utf-8'
<
If 'Content-Type' is specified in the request block, it overrides this
setting.

------------------------------------------------------------------------------
*vrc_horizontal_split*

By default, the output buffer is displayed to the right of the rest buffer
(vertical split). If this option is set, the output buffer is displayed
below the rest buffer.

------------------------------------------------------------------------------
vrc_keepalt

By default, the current alternate file name will be changed. If this
option is set, it will keep the current alternate file.

------------------------------------------------------------------------------
*vrc_output_buffer_name*

This option sets the name for the output/display buffer. By default, it's set
to '__REST_response__'. To assign a different name,
>
    let g:vrc_output_buffer_name = '__NEW_NAME__'
<
This option is useful in working with multiple VRC buffers where each one has
its own output display. For this, the option can be set in the buffer scope as
>
    let b:vrc_output_buffer_name = '__REST_1_OUTPUT__'
<
------------------------------------------------------------------------------
*vrc_response_default_content_type*

This option is to set the default content type of the response. It's useful
when we don't want to include the response header in the output view but
still want the output to be formatted or syntax-highlighted.
>
    let b:vrc_response_default_content_type = 'application/json'
<
or
>
    let g:vrc_response_default_content_type = 'text/xml'
<
------------------------------------------------------------------------------
*vrc_set_default_mapping*

This option is to enable/disable the trigger key mapping. It's enabled by
default. To disable the mapping,
>
    let g:vrc_set_default_mapping = 0
<
Once the mapping is disabled, the request block can be executed by
>
    :call VrcQuery()
<
------------------------------------------------------------------------------
*vrc_show_command*

This option enables the printing of the executed curl command in the output
pane. It's disabled by default. To enable:
>
    let g:vrc_show_command = 1
<
------------------------------------------------------------------------------
*vrc_split_request_body*

Determine if the request body should be processed line by line. Default: 0.

If this option is set, each line of the request body is passed to cURL using
either `--data` or `--data-urlencode` depending on the verb.

If the verb is `GET` and the option |vrc_allow_get_request_body| is enabled,
this option doesn't take effect; the request body is always sent as a whole
using `--data`.

------------------------------------------------------------------------------
*vrc_syntax_highlight_response*

This option enables the syntax highlighting of the response body according to
the Content-Type. It's enabled by default. To disable:
>
    let g:vrc_syntax_highlight_response = 0
<
If the response header isn't present (i.e., no `-i` cUrl option), this option
depends on the option |vrc_response_default_content_type|.

------------------------------------------------------------------------------
*vrc_trigger*

This option defines the trigger key. It's <C-j> by default. To remap the key,
>
    let g:vrc_trigger = '<C-k>'
<
==============================================================================
                                                                    *VrcTnt*
7. Tips 'n Tricks~

------------------------------------------------------------------------------
                                                           *VrcTntDataBulk*
7.1 POST Data in Bulk~

Since v3.0, VRC supports POSTing data in bulk using in-line data or an
external data file. It's helpful for such APIs as Elasticsearch's Bulk API.

To use in-line data, first enable the Elasticsearch support flag.
>
    let g:vrc_elasticsearch_support = 1
<
The request would look like this.
>
    http://localhost:9200
    POST /testindex/_bulk
    { "index": { "_index": "test", "_type": "product" } }
    { "sku": "SKU1", "name": "Product name 1" }
    { "index": { "_index": "test", "_type": "product" } }
    { "sku": "SKU2", "name": "Product name 2" }
<

Using external data files doesn't need the support flag.
>
    http://localhost:9200
    POST /testindex/_bulk
    @data.sample.json
<
------------------------------------------------------------------------------
                                                              *VrcTntStxHi*
7.2 Syntax Highlighting

Though VRC supports output syntax highlighting, it's based on the response
Content-Type. When Content-Type is not present, the output can still be
syntax-highlighted if the appropriate ftplugin is installed. To force the
output highlighting based on `filetype`, place this setting in '.vimrc':
>
    let g:vrc_output_buffer_name = '__VRC_OUTPUT.<filetype>'
<
`filetype` can also be set in the output buffer on an ad hoc basis.
>
    # vim: set ft=json
<
===============================================================================
                                                              *VrcContributors*
8. Contributors~

Thanks to the contributors (in alphabetical order of GitHub account)
>
    @dan-silva
    @dflupu
    @iamFIREcracker
    @jojoyuji
    @korin
    @minhajuddin
    @mjakl
    @nathanaelkane
    @p1otr
    @rawaludin
    @rlisowski
    @sethtrain
    @shanesmith
    @tdroxler
    @tonyskn
    @torbjornvatn
<
===============================================================================
                                                                   *VrcLicense*
9. License~

MIT

 vim:tw=78:ts=4:ft=help:norl: