Using the Wordnik API
Tags: shell, curl, api
Published: 2019-04-02 04:41:45

---
title: Using the Wordnik API
published: true
tags: shell, curl, api
canonical_url: https://denmchenry.com/posts/wordnik-api/
description: "Creating a shell function to get quick dictionary definitions on the command line, because, why not?"
---

One thing I've finally learned is that whether you're running bash or zsh in your terminal, the file where you customize your instance ends with `rc`, which stands for "runcom," or "run commands," dating way back to 1965 in the early days of UNIX. `.bashrc` is the file that contains commands to be run when the bourne again shell (bash) starts up, and `.zshrc` has the commands to be run when the z shell (zsh) starts up. And you'll find it elsewhere, for example in `.vimrc` if you're into Vim.

One of the really cool things you can do here is reference environment variables, aliases, and functions stored in external files. So I wrote the following function using the [Wordnik API](http://developer.wordnik.com/) so I can quickly define words on the command line.

{% gist https://gist.github.com/denmch/f7d9b8e0f01b2ab67ec633ccc9799f9f.js %}

If you don't know [Wordnik](http://wordnik.com/), you should check it out. It's a great site, and when my confirmation email didn't come through Erin McKean quickly responded herself and activated my account, which felt pretty cool.

The function works like a shell command and can take an argument, which is represented within the function as `$@`. This grabs any and all positional parameters, e.g., if the command takes three parameters, they'd be referenced as `$1`, `$2`, `$3`. So `$@` just takes one after the other and passes them all in. The local variables `params` and `params_encoded` turn it into a URL-encode string by replacing the spaces between parameters with `%20` so that the result work `curl` talks to the server.

The `curl` command is one of those that you find all over the web in places like StackOverflow, where people say, "Just type curl blah bitty blah blah." It's just one of those things that you use to do something. But as often happens, it turns out to be helpful to know what the name means, so that you can retain the meaning. In this case, its name is styled cURL, like the ubiquitous acronym URL. It's written in C and though originally meant to be pronounced "see URL," it was later treated as a backronym for "cURL URL Request Library," as the creator described on cURL's 17th birthday. (As of this writing cURL is nearing 20!)

Knowing that history we remember either that cURL allows us to "see" stuff at a given URL, or that it's a library written in C used to request information from and about URLs.

We run `curl` with a `--silent` option. If you were typing this a lot on the command line, it'd be faster to use `-s`, but for the purposes of a readable gist, it seems beneficial to type out the option, explaining clearly that we want our `curl` output to be silent, i.e., to not show us the progress bar, etc. To get a result, you need to add your Wordnik API key (I've added mine as an environment variable sourced in my `.zshrc` file).

We pipe the output through `json` with the `--array` option (aka `-a`), and the lookup parameter `text`, which is the key that should grab each definition in the JSON results from Wordnik.

These results are then piped to `cat` with the `-b` option, which numbers non-blank lines in returned results. I'm not sure the `-b` options is necessary given the results (`-n` could be sufficient), but it doesn't hurt.

So just for fun, here's the result, with the added bonus of piping the output to `cowsay -f stegosaurus` (where the `-f` option is short for "file", i.e., which "cowfile" is used for the ASCII art).

`def learning | cowsay -f stegosaurus`

 ![An screenshot of a terminal window showing ASCII art of a stegosaurus speaking three definitions of the word learning.](https://denmchenry.com/img/stegosaurus-def.png)