<div align="center">

resty.nvim

A fast and easy-to-use HTTP-Rest-Client plugin for Neovim, completely written in LUA.

Features • Install • Syntax • Examples

</div>

Features

These are the features that contribute to this goal:

• meaningful error messages by editing the input file
• completion (if hrsh7th/nvim-cmp is installed) for mainly used headers and possible configurations
• different variables types: from environment variables, shell commands (with cache), input prompt or values
• executing from LUA scripts (post request hook)
• display the values of defined variables without executing the request (simple setting the cursor on the variable-replacement)
• further processing from json result with jq
• create your own favorite list with nvim-telescope/telescope.nvim (if installed) for finding often used request in a large input file
• write the request definition in which file you want (nearby to the code, where you have implement the rest service)
• show information about duration of parsing and executing from the request

Install

• packer.nvim:

  use {
    "lima1909/resty.nvim",
    requires = { "nvim-lua/plenary.nvim" },
  }
  

• lazy.nvim:

  {
    "lima1909/resty.nvim",
    dependencies = { "nvim-lua/plenary.nvim" },
  },
  

Supported Neovim versions:

• Latest nightly
• 0.10.x

Dependencies

• curl (mandatory) execute the request definition
• jq (optional, but recommended) query the response body
• nvim-telescope/telescope.nvim plugin (optional), for using a listing of available favorites
• hrsh7th/nvim-cmp plugin (optional) for headers and configurations completion

Syntax

• global and local variable definition (optional):
  • @[variable-name]=[value] or @[variable-name]={{variable-replacement}}
  • variable-replacement: shell command, environment variable or input prompt
    • variable-replacement are supported in: url, variable-, header- and query-values,
  • configuration variables: for curl (timeout, insecure, proxy, ...) or for resty (check_json_body)
• request definition
  • method (GET, POST, ...) (mandatory):
  • url (http://host, https://host:port, http://127.0.0.1:443?id=7) (mandatory):
  • http version (HTTP/1.0) (optional)
• headers and or query parameter (optional)
• json-body (optional), after the json-body must the request definition ends or an blank line follows
• LUA-script (post request hook) (optional), after the script must the request definition ends or an blank line follows
• other:
  • #: comments
  • ###: delimiter, if more as one request definition, or text before and/or after exist
  • ### #my favorite : delimiter, with defining a favorite ('my favorite') for the easy to finding the request definition

Syntax highlight

There are two supported filetypes:

• http: needs a treesitter installation. This filetype is not 100% compatible!
• resty: has his own vim syntax highlight and don't need additional installations

Syntax in action

# variable for the hostname
@hostname = httpbin.org          # variable with value
@hostname = {{$HOSTNAME}}        # from environment variable (start symbol: '$')
@hostname = {{>  ./myscript.sh}} # from script (start symbol: '>')
@hostname = {{>> ./myscript.sh}} # from script (start symbol: '>>'), the result will be cached
@hostname = {{:hostname}}        # with input prompt (start symbol: ':')

# prefix: @cfg. means configuration from curl and/or resty
@cfg.timeout = 1000              # curl configuration for timeout 
@cfg.check_json_body = true      # resty configuration to validate the json body

###  #my favorite
GET https://{{hostname}}/get?id=7
# you can click (set the cursor) on {{hostname}} and get displayed the current value
accept: application/json  
# id = 7 this equivalent to ?id=7

### 
# local variable overwrites global variable
@hostname = jsonplaceholder.typicode.com

POST https://{{hostname}}/comments
accept: application/json  

{ "comment": "my comment" }

In LUA scripts you can use an ctx table, which has access to the following properties and methods:

local ctx = {
    -- result of the current request
    -- body = '{}', status = 200, headers = {}, exit = 0, global_variables = {}
    result = ...,
    -- set global variables with key and value
    set = function(key, value) end,
    -- parse the JSON body
    json_body = function() end,
    -- jq to the body
    jq_body = function(filter) end,
}

Commands

| User command | Description | |-----------------------------------|---------------------------------------------------------------------------------------| | :Resty run | run request under the cursor OR <br>in visual mode run the marked request rows | | :Resty run [request definition] | run request which is given by input, rows are seperated by \n<br> (you can simulate \n with <C-v><CR> in command mode) | | :Resty last | run last successfully executed request | | :Resty favorite | show a telescope view with all as favorite marked requests | | :Resty favorite [my favorite] | run marked request my favorite, independend, where the cursor is or in which buffer |

Examples for using a command with a keymap configuration:

vim.keymap.set({"n","v"},"<leader>rr", ":Resty run<CR>",{desc="[R]esty [R]un request under the cursor"})
vim.keymap.set({"n","v"},"<leader>rv", ":Resty favorite<CR>",{desc="[R]esty [V]iew favorites"})

Response|Result view

There are four views for the result (the rest-call-response)

| view | short cut | description | |-----------|-----------|----------------------------------------------| | body | b | response body | | headers | h | response headers | | info | i | shows information from the call and response | | ? | ? | shows help information for keybindings |

Short cuts for the view: body

jq must be installed!

| short cut | description | |-----------|-------------------------------| | p | json pretty print | | q | jq query | | r | reset to the origininal json |

Hint: with cc can the curl call canceled.

Examples

Give a star for this great project ;-)

PUT https://api.github.com/user/starred/lima1909/resty.nvim
Authorization: Bearer {{my-token}}
Accept: application/vnd.github+json

Login with saving the result token

POST https://reqres.in/api/login
accept: application/json  
Content-type: application/json ; charset=UTF-8

{
    "email": "eve.holt@reqres.in",
    "password": "cityslicka"
}

# response: { "token": "QpwL5tke4Pnpja7X4" }
# save the token into the variable: {{login.token}}

--{%
  local body = ctx.json_body()
  ctx.set("login.token", body.token)
--%}

Call with query parameter

GET https://reqres.in/api/users
delay = 1

### both are the same
GET https://reqres.in/api/users?delay=1 

Post with body

POST https://api.restful-api.dev/objects
accept: application/json  
Content-type: application/json; charset=UTF-8

{
   "name": "MY Apple MacBook Pro 16",
   "data": {
      "year": 2019,
      "price": 1849.99,
      "CPU model": "Intel Core i9",
      "Hard disk size": "1 TB"
   }
}