loading...
Cover image for No More postman just use cURL + vim = ❤

No More postman just use cURL + vim = ❤

22mahmoud profile image Mahmoud Ashraf Updated on ・3 min read

Originally Published on my blog

Postman one of the most popular API client tool, for send and view the response
in the development environment. But since Postman is proprietary software and
there is a free + open sourced alternative so I'll go for something
like insomnia, or postwoman.

But also I'll go for CLI if exists and cURL is one of
the easy to use and fully featured tool and in this article I'll show you how
to setup a well-documented api with cURL + vim + git.

How to execute CLI inside your vim editor?

vim is very powerful editor and you can execute a command line
inside it. go to command mode and insert :! <command> and hit enter.

for example:

  :! ls

will execute the ls command line and show the content
in pager.

screenshot for ls command inside vim

Execute the content of the current file as CLI.

open an empty file inside your vim and write inside it echo Hello, World! and save it,
and then write :!sh %.

The percent % is refer to the filename so if we run it with normal bang :! %
it will not work because it's trying run the file as executable file not the content inside.

so we pass sh before the % to run the content inside the file via shell.

:!sh command inside vim

Test our first cURL command

for demonstrating we will gonna use jsonplaceholder as our API to test

Create a folder structure like below:

└── api
    └── todos
        ├── delete
        │   └── todo.zsh
        ├── get
        │   ├── todo-by-user.sh
        │   ├── todo.sh
        │   └── todos.sh
        ├── patch
        │   └── todo.sh
        ├── post
        │   └── todo.sh
        └── put
            └── todo.sh

.sh to get file highlighted.

let's start with first and simple one api/posts/get/todos.sh.

write in the file and save.

curl -s -X GET \
    'https://jsonplaceholder.typicode.com/todos'

then as we done before run :!sh %

screenshot of :!sh % result inside vim

Make the result More Handy.

In most tools you will get a split view for the request itself
and the result.

open you vim config file and add

command Exec set splitright | vnew | set filetype=sh | read !sh #

the command before will open the result in a new buffer in vertical view.

if you prefer horizontal view you can change the command to

command Exec set splitbelow | new | set filetype=sh | read !sh #

open again api/posts/get/todos.sh and in command mode write :Exec
that will execute the command inside the file and open split view with the result.

screenshot of before vim command

now you have vim buffer you can easily search and do whatever you do. and to close the buffer you can use
command :bd! or the keyboard shortcut shift + z + q.

Is cURL limited?

The answer is NO.
let's see couple of example

  • POST Request:
curl -s -X POST \
    'https://jsonplaceholder.typicode.com/posts' \
    -H 'Content-Type: application/json' \
    -d '{ "title": "fooBatch", "completed": false, "userId": 1 }' \

you can make post, get, put, .. or any http request by using -X <REQUEST_TYPE> option.

To pass the body data use -d, --data {json format>} , and if the data is large
you can write it in json file and pass it as -d @todo.json

  • GET Request with query params:
curl -s -X GET -G \
    'https://jsonplaceholder.typicode.com/todos' \
    -d 'userId=1'

you can still use query params with -d but add an additional -G, --get to pass it as query params

since this is not a cURL tutorial that's will be enough and you
can learn more about advanced stuff like set header, cookie and more from the internet.

Using git?

Of course, on our created directory run git init and push for example to github.

see this example on github

Conclusion

You can now write a well-documented api and share it with your friends via git
all that done with simple and open-sourced tools and that's not limited to cURL
you can write you own scripts and run it inside vim, or pipe cURL command for anther
tools to manipulate the output for example jq so you can filter your output.



Posted on by:

Discussion

pic
Editor guide
 

When you want change website, you need change all scripts. Why you don't inject main part of URL into all scripts as parameter?

My potential structure of this:

└── api
    └── todos
        ├── delete.sh
        ├── get.sh
        ├── get-by-user.sh
        ├── get-all.sh
        ├── patch.sh
        ├── post.sh
        └── put.sh

But still is too much repeated parts of this. Maybe one script with one switch?

 

You can structure the files as you want.

to change the baseurl you can run

sed -in 's/https:\/\/jsonplaceholder.typicode.com/https:\/\/new_base_url.com/' api/todos/**/*.sh

or you can use vim-rest-console as some comments mentioned.

 

The point is to make things easy and avoid havind to remember a bunch of things just to do somethin, this ifs the opposite of automation

 

I used to do something like this, but not as organize as you describe. Eventually it got a little messy so I ended up creating a cli tool for myself, I call it tinytina. Now I put the api info in a json file and call each endpoint with an "id".

tinytina --schema ./api-data.json --env dev run posts:list-all

I can even turn that into a curl/httpie command, so I can share it with others.

tinytina --schema ./api-data.json --env dev convert-to curl posts:list-all
 

You could use vim VRC github.com/diepm/vim-rest-console , it allows you to store your requests in a file like http.rest

http://localhost:9200
POST /testindex/testtype
{
  "key": "new key",
  "value": "new value"|
}
 

It has cool features, I'll give it a try.

 

Interesting article and sparkle my interest to write a small function for this as you cannot really read a buffer with a command.

function M.Exec()
  lines = vim.fn.getline(1, '$')
  command = ''
  for key, val in pairs(lines) do .
    command = command .. val
  end
  output = vim.fn.systemlist(command)
  vim.api.nvim_command('rightbelow new')
  buf = vim.api.nvim_get_current_buf() 
  vim.api.nvim_buf_set_lines(buf, 0, -1, false, output)
end
return M

Forgot to mention you need to have the latest neovim to enjoy built in lua.

 

The main Reason why I use Postman rather then Curl+ vim...

  • it usually take 8-9 days to design a badass backend, so I worry about response and other thing, rather then using curl.Postman easy

  • Main
    I am a full stack developer, so I need to send the api request's multiple time, just like:
    Sigin Signout add to database delete etc etc..

Which requires each time auth, and sending data where post man saves the previous response in terms of Input and Output..

Sending Authorization, formdata etc etc is too easy by using postman

Also the saved requests make it easy to use and test..

Curl is also good, but Postman Makes live too easy..

 

I like this plugin for to do the requests

 

I like that i can set base url and just set the end points, I'll give it a try.

 

For me, I replaced it with VS Code and REST client extension

 

Well, I mean... The point of using Postman is to organize and to avoid dealing with Curl, and to have a pretty UI so you can just click things.

If I have to run away from postman (I use Insomnia nowdays), I would prefer using a testing framework like rspec or pytest so I can keep tjings documented and use a nicer request library.

Curl has always been the default go-to quick-for-testing sny api endpoint, jowever things can get dofficulot if you have to sign your requests like with AWS endpoints, where not even postman would bee a good alternative.

I guess my two cents here is: curl has always been there for you and always have been, but using it as a postman alternative has the potential to consume your time

 

Nice write-up. I like doing things like this in native vim. Why leave when you don't have to. Thanks!

 

Great article Mahmoud. I also enjoyed using httpie though i still stick to Postman for the day to day.