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 native cURL bindings. In this way, you get absolutely all the power that cURL provides from the comfort of our editor just by using a keybind and without wasting the precious resources of your machine.

In addition to this, you can also write integrations with external HTTP clients, such as the postman CLI. For more information on this, please see this blog post.

Features

• Easy to use
• Friendly and organized 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
• Possibility of using dynamic/environment variables and Lua scripting in HTTP files

Install

Note

rest.nvim requires Neovim >= 0.9.2 to work.

Dependencies

• System-wide
  • Python (only if you are using packer.nvim or lazy.nvim plus luarocks.nvim for the installation)
  • cURL development headers (usually called libcurl-dev or libcurl-devel depending on your Linux distribution)
• Optional can be changed, see config below
  • jq (to format JSON output)
  • tidy (to format HTML output)

Note

1. Python will be unnecessary once luarocks.nvim gets rid of it as a dependency in the go-away-python branch.
2. I will be working on making a binary rock of Lua-cURL so that the cURL development headers are not necessary for the installation process.

rocks.nvim (recommended)

:Rocks install rest.nvim

lazy.nvim

	{
		"vhyrro/luarocks.nvim",
		priority = 1000,
		config = true,
	},
	{
		"Blockhead-Consulting/rest.nvim",
		ft = "http",
		dependencies = { "luarocks.nvim" },
		config = function()
			require("rest-nvim").setup()
		end,
	},

Note

There's a build.lua file in the repository that lazy.nvim will find and source to install the luarocks dependencies for you by using luarocks.nvim. You don't need to specify a rock list by yourself.

Default configuration

This is the default configuration of rest.nvim, it is fully documented and typed internally so you get a good experience during autocompletion :)

Note

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

local default_config = {
  client = "curl",
  env_file = ".env",
  env_pattern = "\\.env$",
  env_edit_command = "tabedit",
  encode_url = true,
  skip_ssl_verification = false,
  custom_dynamic_variables = {},
  logs = {
    level = "info",
    save = true,
  },
  result = {
    split = {
      horizontal = false,
      in_place = false,
      stay_in_current_window_after_split = true,
    },
    behavior = {
      decode_url = true,
      show_info = {
        url = true,
        headers = true,
        http_info = true,
        curl_command = true,
      },
      statistics = {
        enable = true,
        ---@see https://curl.se/libcurl/c/curl_easy_getinfo.html
        stats = {
          { "total_time", title = "Time taken:" },
          { "size_download_t", title = "Download size:" },
        },
      },
      formatters = {
        json = "jq",
        html = function(body)
          if vim.fn.executable("tidy") == 0 then
            return body, { found = false, name = "tidy" }
          end
          local fmt_body = vim.fn.system({
            "tidy",
            "-i",
            "-q",
            "--tidy-mark",      "no",
            "--show-body-only", "auto",
            "--show-errors",    "0",
            "--show-warnings",  "0",
            "-",
          }, body):gsub("\n$", "")

          return fmt_body, { found = true, name = "tidy" }
        end,
      },
    },
    keybinds = {
      buffer_local = true,
      prev = "H",
      next = "L",
    },
  },
  highlight = {
    enable = true,
    timeout = 750,
  },
  ---Example:
  ---
  ---```lua
  ---keybinds = {
  ---  {
  ---    "<localleader>rr", "<cmd>Rest run<cr>", "Run request under the cursor",
  ---  },
  ---  {
  ---    "<localleader>rl", "<cmd>Rest run last<cr>", "Re-run latest request",
  ---  },
  ---}
  ---
  ---```
  ---@see vim.keymap.set
  keybinds = {},
}

Tree-Sitter parsing

rest.nvim uses tree-sitter as a first-class citizen, so it will not work if the required parsers are not installed. These parsers are as follows and you can add them to your ensure_installed table in your nvim-treesitter configuration.

ensure_installed = { "lua", "xml", "http", "json", "graphql" }

Or manually run :TSInstall lua xml http json graphql.

Keybindings

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

However, rest.nvim exposes a :Rest command in HTTP files that you can use to create your keybinds easily. For example:

keybinds = {
  {
    "<localleader>rr", "<cmd>Rest run<cr>", "Run request under the cursor",
  },
  {
    "<localleader>rl", "<cmd>Rest run last<cr>", "Re-run latest request",
  },
}

You can still also use the legacy <Plug>RestNvim commands for mappings:

• <Plug>RestNvim, run the request under the cursor
• <Plug>RestNvimLast, re-run the last request

Note

1. <Plug>RestNvimPreview has been removed, as we can no longer implement it with the current cURL implementation.
2. The legacy <Plug> mappings will raise a deprecation warning suggesting you to switch to the :Rest command, as they are going to be completely removed in the next version.

Usage

Create a new http file or open an existing one and place the cursor over the request and run the :Rest run command.

Note

1. You can find examples of use in the tests directory.
2. rest.nvim supports multiple HTTP requests in one file. It selects the request in the current cursor line, no matters the position as long as the cursor is on a request tree-sitter node.

---

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()

If running Ubuntu or Debian based systems you might need to run ln -s $(which fdfind) ~/.local/bin/fd to get extension to work. This is becuase extension runs the fd command.

Here is a preview of the extension working :)

Mappings

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

Config

• env_pattern: For env file pattern
• env_edit_command: For env file edit command

Select environment alternative

If you are not using telescope, this custom keybind can let you select an environment

vim.keymap.set('n', ',q', function()
  local pattern = _G._rest_nvim.env_pattern
  local command = string.format("fd -HI '%s'", pattern)
  local result = io.popen(command):read('*a')

  local env_list = {}
  for line in result:gmatch('[^\r\n]+') do
    table.insert(env_list, line)
  end

  local rest_functions = require('rest-nvim.functions')

  vim.ui.select(env_list, {
    prompt = 'Select env file ',
    format_item = function(item)
      return item
    end,
  }, function(choice)
    if choice == nil then
      return
    end
    rest_functions.env('set', choice)
  end)
end, { desc = '[q]uery envs' })

Lualine

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/outragedline/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 and lua5.1 or luajit 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.