How to use curl and jq with web APIs

You can query web APIs easily with curl. If the API endpoint accepts GET requests, then this is as simple as:

curl "https://web.site/?parameter1=value1&parameter2=value2"

(The quotes are important here so that your shell doesn’t interpret & as a request to background curl!)

For APIs that use GET/POST/PUT/etc. request types, combine the --data and --request parameters:

curl --request POST \
     --data "parameter1=value1&parameter2=value2" \
            "https://web.site/"

The --data parameter can also be specified multiple times (mostly for readability), in which case you’d normally want to have a single parameter/value pair for each instance.

curl --request POST \
     --data "parameter1=value1" \
     --data "parameter2=value2" \
            "https://web.site/"

By default, curl sends data with the Content-Type: application/x-www-form-urlencoded. If you need to change the content type (for example, you frequently need to send Content-Type: application/json with JSON data) or need to specify additional headers (frequently for authentication), then you can use the --header parameter.

curl --request POST \
     --header "User-Token: XXXXXX" \
     --data "parameter1=value1" \
     --data "parameter2=value2" \
            "https://web.site/"

Like --data, the --header parameter can be specified multiple times for multiple headers, and will smartly override curl’s defaults.

curl --request POST \
     --header "User-Token: XXXXXX" \
     --header "Username: My User" \
     --data "parameter1=value1" \
     --data "parameter2=value2" \
            "https://web.site/"

Because responses are often served up in a compact fashion, they’re often a bit hard to read. The jq command’s default filter (.) just pretty-prints (and colorizes!) JSON, which can make interpreting the API’s response much easier.

curl --request POST \
     --header "User-Token: XXXXXX" \
     --header "Username: My User" \
     --data "parameter1=value1" \
     --data "parameter2=value2" \
            "https://web.site/" | jq .