Exploring APIs with Neovim and Hurl
Tags: hurl, neovim, api, postman
Published: 2023-09-11 19:14:25

Original article: https://www.ethancarlsson.dev/blog/exploringapiswithneovimandhurl

[Hurl](https://hurl.dev/) is a very interesting project that extends the functionality of `curl`. 
It offers an alternative to more GUI oriented software like Postman.

> Hurl is foremost a command line tool and should be easy to use on a local 
> computer, or in a CI/CD pipeline. Some tools in the same space as Hurl
> (Postman for instance), are GUI oriented, and we find it less attractive than 
> CLI
-- [Hurl FAQ](https://hurl.dev/docs/frequently-asked-questions.html)

This caught my attention. I've been a user of Postman for a while, but over time
I've found the tool to be more and more clunky, especially when working on
larger projects.

- It's awkward to navigate.
- It can be slow and memory hungry, especially when there are lots of tabs open.
- It's written with the mouse in mind, keyboard shortcuts feel more like an 
  afterthought.
- It's hard, or at least awkward, to integrate into other tools.

All of these problems have been resolved for me by combining Neovim and Hurl.
To do this I wrote a plugin, [nvim-hurl.nvim](https://github.com/ethancarlsson/nvim-hurl.nvim), 
it runs hurl files and displays the response those files get from the server.

Using this setup I was able to solve all the issues I had with Postman 
leveraging the power of Neovim and Hurl together.

- Jumping around files with a fuzzy finder like [Telescope](https://github.com/nvim-telescope/telescope.nvim)
  or [fzf](https://github.com/junegunn/fzf.vim) is a lot more comfortable. I don't 
  waste time scrolling through tabs or searching through giant collections 
  anymore.
- This will depend on the plugins you use, but for the most part Neovim is a 
  lot lighter Postman. More importantly, I don't find myself in the situation
  where I have 1000 tabs open anymore. This is a user problem to some extent, I
  could always just close tabs, but Postman's design really encourages it.
- Using Vim keybindings means I automatically get a more keyboard centered 
  workflow. 
- Once I'm done editing the Hurl files, I can run them however I want. It was 
  easy to integrate into Neovim, it's easy to integrate it into a CLI, and it 
  would be easy to integrate it into anything that can run command line tools.

This setup also let me take advantage of the entire neovim plugin ecosystem.

- I get highlighting from Treesitter. There's already support for 
  [hurl](https://github.com/pfeiferj/tree-sitter-hurl)
  files, and by setting the file type of the response we get highlighting there
  as well.
- If there's an LSP running, it can be used on the response. There's no support
  Hurl files yet, but it's convenient when you need to format json responses for
  example.
- I've already mentioned it, but fuzzy finding in Neovim is great.

The plugin also offers additional features for hurl, like being able to swap in
and out [variable files](https://hurl.dev/docs/manual.html#variables-file) with 
`Hurlsvf {variables_file}`.

![gif showing off Hurlsvf and HurlRun](https://raw.githubusercontent.com/ethancarlsson/nvim-hurl-images/master/example_gifs/nvimhurl.gif) 

This lets you change URL like in the demonstration above, but could also be used
to quickly and easily change OAuth tokens for example.

It also offers a way to interactively explore APIs with a command named 
`CurlGoFromCursor`. It runs a simple curl command from your cursor allowing you
to quickly navigate through links in RESTful APIs.

![gif showing off HurlGoFromCursor](https://raw.githubusercontent.com/ethancarlsson/nvim-hurl-images/master/example_gifs/GoFromCursor.gif)

Because the Hurl file is just text, and the response is just text,
it’s very easy to add functionality to the plugin and very easy to
integrate into an existing workflow. Hurl might not have all the features 
of some of its GUI competitors at the moment, but it doesn't need those 
features if it's so easy to integrate it into other tools that have those 
features.