I’ve been working a lot with REST APIs recently from the terminal, and I’ve upped my bash-foo a little, so let me share it with you. Of course, you can always escape to a programming language like Ruby or Node, but sometimes bash can get you very far.

Tools

The tools I come back to basically are:

  • bash - For scripting.
  • curl - For doing HTTP requests.
  • jq - For parsing and colorizing JSON output and generating CSVs.
  • csvkit - Work with CSVs for easier parsing (which comes in another blog).

Curl

Curl, the old trusty steed, will be used with the -H to supply the headers and the tokens from a file. As a convention, the header file is the same name as the domain. Don’t forget to add it to your .gitignore.

You can also use -d @mybody.txt to add body data. The f param is to fail with an error if the return isn’t status code 200.

Let’s make a header file notion.txt first. You will need to replace the XXX with your notion token, and don’t forget to share the page with the integration under the share button.

The notion.txt:

Authorization: Bearer XXXX
Content-Type: application/json
Notion-Version: 2021-07-27

And to query:

curl -fH @notion.txt https://api.notion.com/v1/pages/cce9a48b-2a29-4ed7-8a1b-ed0cbd2ba5ac

Doing a POST to query the DB:

curl -fH @notion.txt -X POST \
https://api.notion.com/v1/databases/849170c3ebcb4015aa6c6f935d4cf768/query | jq

Jq

Often times, the JSON you get back is not in the shape you want it, or just way too bloated or unformatted. You can use JQ to slim it down or format things.

To format the JQ and save it in a file:

curl -fH @myapi.txt -X GET https://myapi.com/customers | jq > data.json

Or you can use it to slice up some data:

curl -fH @notion.txt https://api.notion.com/v1/databases/849170c3ebcb4015aa6c6f935d4cf768 \
  | jq '.properties'

You can also use the @csv to function in jq to generate CSV files.

Csvkit

Will write about this in a future post :)```