GitHub - rest-nvim/rest.nvim: A very fast, powerful, extensible and asynchronous Neovim HTTP client written in Lua.

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

Dependencies

Neovim >= 0.10.1
curl
tree-sitter-http (if you use lazy.nvim)

rocks.nvim (recommended)

lazy.nvim

{
  "rest-nvim/rest.nvim",
  dependencies = {
    "nvim-treesitter/nvim-treesitter",
    opts = function (_, opts)
      opts.ensure_installed = opts.ensure_installed or {}
      table.insert(opts.ensure_installed, "http")
    end,
  }
}

Important

You need lazy.nvim higher than v11 to install rockspec dependencies

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,
                ---@type table<string, Certificate> Table containing certificates for each domains
                certificates = {},
            },
        },
    },
    ---@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.*",
        ---@type fun():string[]
        find = function()
            local config = require("rest-nvim.config")
            return vim.fs.find(function(name, _)
                return name:match(config.env.pattern)
            end, {
                path = vim.fn.getcwd(),
                type = "file",
                limit = math.huge,
            })
        end,
    },
    ---@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,
}

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

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

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 to install dependencies. The test runner through make test will automatically install all required dependencies.

Related software

License

rest.nvim is GPLv3 Licensed.