rest.nvim

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.

Important

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

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

Python will be unnecessary once luarocks.nvim gets rid of it as a dependency in the go-away-python branch.
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,
},
{
  "rest-nvim/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.

packer.nvim

use {
  "rest-nvim/rest.nvim",
  rocks = { "lua-curl", "nvim-nio", "mimetypes", "xml2lua" },
  config = function()
    require("rest-nvim").setup()
  end,
}

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,
      },
    },
  },
  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

<Plug>RestNvimPreview has been removed, as we can no longer implement it with the current cURL implementation.
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

You can find examples of use in the tests directory.
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

Lualine

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

And dont'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

Fork it (https://github.com/rest-nvim/rest.nvim/fork)
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'feat: add some feature')
Push to the branch (git push -u origin my-new-feature)
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

License

rest.nvim is GPLv3 Licensed.

amagee/rest.nvim

rest.nvim

Features

Install

Dependencies

rocks.nvim (recommended)

lazy.nvim

packer.nvim

Default configuration

Tree-Sitter parsing

Keybindings

Usage

Telescope Extension

Mappings

Config

Lualine

Contribute

Related software

License