DEV Community

Ethan Carlsson
Ethan Carlsson

Posted on

nvim-hurl and Some Intuitions on UX

#ux #programming #neovim #ui

I just made a new release to a plugin I've developed to run hurl files (https://hurl.dev/)
in Neovim (https://github.com/ethancarlsson/nvim-hurl.nvim/releases/tag/v1.2.0).
I really like working on this project, it's designed for me to use and so when
I add features I only ever add the features that I'm actually going to use.

In this case I added additional functionality to work with temporary variables.
I've always found variables kind of awkward to use in tools like Postman, you end
up clicking through so much UI to add a variable that in all likelihood you'll need
to change the next time you run the command. For that reason I didn't put much
effort into variables, and in practice I only use variables that I know aren't
going to change often, like {{host}} and {{auth_token}}. Copy and pasting
the other values is almost always quicker and more ergonomic than creating variables
when your exploring an API. The only case where I'll use variables is if I'm intending
to run the file as a test and not edit it.

They can however be used to solve a problem though. When your working on http APIs
a common issue is that in order to create a resource you need to first get the ID
of a related resource.

POST {{url}}/orders
Enter fullscreen mode Exit fullscreen mode 
{
  "items": [
    {
      "id": "ce039087-835a-4484-89dc-70c2ea123b40"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

In order to create this order I need to first retrieve the ID of the item and copy
and past it into this request. This can get tedious when there's multiple IDs or
if I want to test out multiple items.

So it would be convenient if I could have this:

POST {{url}}/orders
Enter fullscreen mode Exit fullscreen mode 
{
  "items": [
    {
      "id": "{{id}}"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

That way I don't need to worry about having to edit the file, I just update the
variable. But this get's us back to the original problem I was facing with tools
like Postman, setting the variable is often just as much work as just copying and
pasting it into the file. So how do we make it less effort.

My trick was to build on my existing workflow, so I still copy things, but now
if I copy this object all the variables can be automatically mapped to hurl variable
template variables.

{
  "id": "2ab2e8d4-ae06-44e6-9ae3-c0891185bfe2",
  "sku": "boo/US-/Gre/Bla",
  "item_name": "Grey Boots"
}
Enter fullscreen mode Exit fullscreen mode

You copy the object and then run :Hurlsvr "* (you don't have to write the whole, just remap it),
then {{id}}, {{sku}} and {{item_name}} will all be populated by the values
in the object. This way I can scroll through a list of items and whenever I want
to change the variables I just yank them into
a register.

This still doesn't really fit how I work though, usually a just need to select a
couple of variables, so I use this configuration

vim.keymap.set(
    "n",
    "<leader>yh",
    [["8yy<cmd>Hurlsvr "8<CR>]], -- You can use a different register if you want "8 was arbitrarily chosen
    { desc = "Yank line to register and then to hurl variables" }
)
Enter fullscreen mode Exit fullscreen mode

This automates pulling the value from the register and lets me select just a given
line, I just need the ID so using this I can just yank this line"id": "2ab2e8d4-ae06-44e6-9ae3-c0891185bfe2",
and it will make just {{id}} accessible in the hurl file. More importantly,
it will do it in just three key strokes.

This still has a disadvantage over the good old fashioned copy and past functionality,
when you've copied and pasted you know the variable is there and you know it's value.
I added completions to the plugin to make the variables more transparent, you can
see what variables are available and the contents of the variable.

Some intuitions on UX

I'd like to use the changes I made here to help systematize my own intuitions about
what makes good UX.

  1. Good UX involves less actions. All else equal, if you can do the same thing in less clicks, key presses, etc., you should.
  2. Good UX matches the users exact use case. The ability to turn partial JSON into hurl variables is incredibly specific and it's exactly what I need. I considered making it work with YAML or to be able to parse variables in the format that hurl uses (key=var). But that's not how I use it and the extra support would just complicate the tool.
  3. Good UX fits into existing UI, it doesn't introduce new UI elements. I considered introducing a pop-up to be able to see what variables are active, but in the end found that the completions were enough for me to be able to get an idea of what variables I can use. Since I already use completions in Neovim I don't need to change the way I use the Neovim very drastically when manipulating hurl files.

These intuitions are very specific to how I use this plugin. There are some things
I don't need to think about, like making it easy to learn how to use it or account
for different use cases. But this is a plugin just for me, so I don't have to think
about those things, and that's what has made it such a fun project to work on.

Top comments (1)

Collapse
 
youngfra profile image
Fraser Young •

How does your temp variable workflow handle nested JSON (e.g., items[0].id), collisions, and reuse across multiple hurl files? Maybe write next about your completion design and keymap setup, with a quick comparison to hurl env files and Postman variables.