rest.nvim

Features • Install • Usage • Contribute

---

A very fast, powerful, extensible and asynchronous Neovim HTTP client written in Lua.

rest.nvim by default makes use of its own curl wrapper made in pure Lua and a tree-sitter parser to parse http files. So what you can run get exact and detailed result what you see from your editor!

In addition to this, you can also write integrations with external HTTP clients, such as the postman CLI.

Important

If you are facing issues, please report them so we can work in a fix together :)

Features

• Easy to use
• Friendly, organized and featureful request results window
• Fast runtime with statistics about your request
• Set custom pre-request and post-request hooks to dynamically interact with the data
• Easily set environment variables based on the response to re-use the data later
• Tree-sitter based parsing and syntax highlighting for speed and perfect accuracy
• Format response body with native gq command
• Possibility of using dynamic/environment variables and Lua scripting in HTTP files
• Save received cookies and load them automatically

Install

Note

rest.nvim requires Neovim >= 0.10.1 to work.

Dependencies

• curl
• tree-sitter-http (scm version)

rocks.nvim (recommended)

:Rocks install rest.nvim
:Rocks install tree-sitter-http dev

lazy.nvim

{
  "rest-nvim/rest.nvim",
}

Note

you also need to install latest tree-sitter-http parser using :TSInstall http

Setup

No .setup() call is needed! Just set your options via vim.g.rest_nvim. It is fully documented and typed internally so you get a good experience during autocompletion :)

---@type rest.Opts
vim.g.rest_nvim = {
    -- ...
}

Note

You can also check out :h rest-nvim.config for documentation.

Default configuration

---rest.nvim default configuration
---@class rest.Config
local default_config = {
    ---@type table<string, fun():string> Table of custom dynamic variables
    custom_dynamic_variables = {},
    ---@class rest.Config.Request
    request = {
        ---@type boolean Skip SSL verification, useful for unknown certificates
        skip_ssl_verification = false,
        ---Default request hooks
        ---@class rest.Config.Request.Hooks
        hooks = {
            ---@type boolean Encode URL before making request
            encode_url = true,
            ---@type string Set `User-Agent` header when it is empty
            user_agent = "rest.nvim v" .. require("rest-nvim.api").VERSION,
            ---@type boolean Set `Content-Type` header when it is empty and body is provided
            set_content_type = true,
        },
    },
    ---@class rest.Config.Response
    response = {
        ---Default response hooks
        ---@class rest.Config.Response.Hooks
        hooks = {
            ---@type boolean Decode the request URL segments on response UI to improve readability
            decode_url = true,
            ---@type boolean Format the response body using `gq` command
            format = true,
        },
    },
    ---@class rest.Config.Clients
    clients = {
        ---@class rest.Config.Clients.Curl
        curl = {
            ---Statistics to be shown, takes cURL's `--write-out` flag variables
            ---See `man curl` for `--write-out` flag
            ---@type RestStatisticsStyle[]
            statistics = {
                { id = "time_total", winbar = "take", title = "Time taken" },
                { id = "size_download", winbar = "size", title = "Download size" },
            },
            ---Curl-secific request/response hooks
            ---@class rest.Config.Clients.Curl.Opts
            opts = {
                ---@type boolean Add `--compressed` argument when `Accept-Encoding` header includes
                ---`gzip`
                set_compressed = false,
            },
        },
    },
    ---@class rest.Config.Cookies
    cookies = {
        ---@type boolean Whether enable cookies support or not
        enable = true,
        ---@type string Cookies file path
        path = vim.fs.joinpath(vim.fn.stdpath("data") --[[@as string]], "rest-nvim.cookies"),
    },
    ---@class rest.Config.Env
    env = {
        ---@type boolean
        enable = true,
        ---@type string
        pattern = ".*%.env.*",
    },
    ---@class rest.Config.UI
    ui = {
        ---@type boolean Whether to set winbar to result panes
        winbar = true,
        ---@class rest.Config.UI.Keybinds
        keybinds = {
            ---@type string Mapping for cycle to previous result pane
            prev = "H",
            ---@type string Mapping for cycle to next result pane
            next = "L",
        },
    },
    ---@class rest.Config.Highlight
    highlight = {
        ---@type boolean Whether current request highlighting is enabled or not
        enable = true,
        ---@type number Duration time of the request highlighting in milliseconds
        timeout = 750,
    },
    ---@see vim.log.levels
    ---@type integer log level
    _log_level = vim.log.levels.WARN,
    ---@class rest.Config.DebugInfo
    _debug_info = {
        -- NOTE: default option is `nil` to prevent overwriting as empty array
        ---@type string[]
        unrecognized_configs = nil,
    },
}

Usage

Create a new http file or open an existing one and run the :Rest run {name} command, or just place the cursor over the request and simply run :Rest run.

HTTP file syntax

Method Request-URI HTTP-Version
Header-field: Header-value

Request-Body

Note

rest.nvim follows intellij's http client spec for .http file syntax. You can find examples of use in the spec/examples directory.

Keybindings

By default rest.nvim does not have any key mappings except the result buffers so you will not have conflicts with any of your existing ones.

Commands

User Command	Behavior
:Rest open	Open result pane
:Rest run	Run request under the cursor
:Rest run {name}	Run request with name {name}
:Rest last	Run last request
:Rest logs	Edit logs file
:Rest cookies	Edit cookies file
:Rest env show	Show dotenv file registered to current .http file
:Rest env select	Select & register .env file with vim.ui.select()
:Rest env set {path}	Register .env file to current .http file

[!INFO] All :Rest subcommands opening new window support command-modifiers (:h command-modifiers.) For example, you can run :hor Rest open to open result pane in horizontal split.

See :h rest-nvim.commands for more info

Lua scripting

http://localhost:8000

# @lang=lua
> {%
local json = vim.json.decode(response.body)
json.data = "overwritten"
response.body = vim.json.encode(json)
%}

Put # @lang=lua comment just above any script elements. Scripts without @lang will be parsed as javascript code to match with http spec.

Extensions

Telescope Extension

rest.nvim provides a [telescope.nvim] extension to select the environment variables file, you can load and use it with the following snippet:

-- first load extension
require("telescope").load_extension("rest")
-- then use it, you can also use the `:Telescope rest select_env` command
require("telescope").extensions.rest.select_env()

Here is a preview of the extension working :)

Mappings

• Enter: Select Env file
• Ctrl + O: Edit Env file

Config

• config.env.pattern: For env file pattern (lua-pattern)

Lualine Component

We also have lualine component to get what env file you select!

And don't worry, it will only show up under HTTP files.

-- Just add a component in your lualine config
{
  sections = {
    lualine_x = {
      "rest"
    }
  }
}

-- To use a custom icon and color
{
  sections = {
    lualine_x = {
      {
        "rest",
        icon = "",
        fg = "#428890"
      }
    }
  }
}

Here is a preview of the component working :)

Contribute

1. Fork it (https://github.com/rest-nvim/rest.nvim/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'feat: add some feature')
4. Push to the branch (git push -u origin my-new-feature)
5. Create a new Pull Request

Important

rest.nvim uses semantic commits that adhere to semantic versioning and these help with automatic releases, please use this type of convention when submitting changes to the project.

Tests can be ran via make test. You must have luarocks installed to install dependencies. The test runner through make test will automatically install all required dependencies.

Related software

• vim-rest-console
• Hurl
• HTTPie
• httpYac

License

rest.nvim is GPLv3 Licensed.