Build a REST API Client in Bash Using curl and jq

When people think of REST API clients, they often imagine sophisticated libraries in Python or JavaScript. But with just a bit of Bash, curl, and jq, you can interact with APIs directly from the command line. This is especially useful for scripting, automation, or quick testing without pulling in heavier tools or languages.

1. Prerequisites: Setting Up the Environment

Before diving into code, make sure you have the essential tools installed:

curl – a command-line tool for making HTTP requests
jq – a lightweight JSON processor

Install them using your package manager:

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install curl jq

# macOS with Homebrew
brew install curl jq

Once you’ve got those in place, you’re ready to call APIs and parse responses like a pro.

2. Making Your First API Request with curl

Let’s start with a simple GET request to the GitHub API to fetch a user’s public information. Replace {username} with a valid GitHub username:

#!/bin/bash
USERNAME="octocat"
RESPONSE=$(curl -s "https://api.github.com/users/$USERNAME")
echo "$RESPONSE"

This script makes a GET request and saves the API response in a shell variable. The -s flag tells curl to run silently, which cleans up the output by removing the progress bar.

Try running it and you’ll see a wall of JSON. Now let’s make that output useful.

3. Parsing JSON Output with jq

jq is a powerful, flexible tool for querying and transforming JSON data. Let’s extract the user’s name and number of public repositories:

NAME=$(echo "$RESPONSE" | jq -r '.name')
REPO_COUNT=$(echo "$RESPONSE" | jq -r '.public_repos')
echo "User: $NAME has $REPO_COUNT public repositories."

The -r flag in jq tells it to output the raw string without quotes. Without it, shell variables will contain quote characters, which can cause confusion in later processing.

This kind of parsing is what makes jq so powerful when working with JSON pipelines.

4. Real-World Example: Fetching Weather Data from OpenWeatherMap

Let’s construct a client that pulls current weather using the OpenWeatherMap API. You’ll need an API key from their website. Here’s how to build the script:

#!/bin/bash
API_KEY="your_openweathermap_api_key_here"
CITY="London"
RESPONSE=$(curl -s \
  "https://api.openweathermap.org/data/2.5/weather?q=$CITY&appid=$API_KEY&units=metric")

TEMP=$(echo "$RESPONSE" | jq -r '.main.temp')
DESC=$(echo "$RESPONSE" | jq -r '.weather[0].description')
echo "Current weather in $CITY: $TEMP°C, $DESC"

Use the units=metric query parameter to get the temperature in Celsius. This script shows how easy it is to create automated weather updates or text alerts with only a few lines of Bash.

5. Tips for Robust Bash API Clients

To make your Bash API client more reliable, consider the following enhancements:

Error handling: Use curl’s --fail option and jq‘s error checking.
Rate limiting: Some APIs restrict how often you can call them. Add sleep delays or use caching where needed.
Modular scripts: Break large scripts into functions for maintainability.
Authentication: For APIs requiring authentication tokens or headers, pass them with -H flags in curl.

Here’s an example with a token:

curl -s -H "Authorization: Bearer $TOKEN" https://api.example.com/data

Curl allows you to add any number of headers, and combined with jq, it becomes a formidable scripting tool for interacting with modern APIs.

Final Thoughts

Using curl and jq in Bash scripts is a lightweight yet powerful way to work with REST APIs. Whether you’re monitoring systems, building automation tools, or just consuming data, knowing how to interact with APIs from the command line is an essential skill for modern developers and sysadmins.

Try extending your scripts to handle POST requests, send JSON payloads, or write logs to a file. From automation to cron jobs and dashboards, the simplicity of Bash combined with the versatility of curl and jq opens up a world of possibilities.

Useful links: