cURL command-line

cURL is the common tool for API debugging. Every API doc page has cURL examples for a reason: they work in any shell, they show exactly what is sent and received, and the output is plain text you can pipe into anything. This guide is a list of recipes you can copy and adapt for the GoRest endpoints, plus the jq filters that turn raw JSON into something readable.

Set up the token

Put the token in an environment variable so you do not paste it into your shell history. From here on, every example uses $TOKEN for the bearer token.

export TOKEN=YOUR_TOKEN # from /my/tokens
export API=https://gorest.co.in/public/v2

List resources

The four read endpoints follow the same shape: /users, /posts, /comments, /todos. They return JSON arrays directly (no data wrapper). Pipe through jq to read them in a terminal:

curl -sS -H "Authorization: Bearer $TOKEN" \
     "$API/users?status=active&page=1" | jq '.[0]'

curl -sS -H "Authorization: Bearer $TOKEN" \
     "$API/posts?page=2" | jq '.[].title'

The -sS combination is the one to remember: -s hides the progress meter, -S turns error reporting back on (so the script still fails loudly when something is wrong). Without -s you cannot pipe to jq cleanly, because cURL prints the progress bar to stderr and it still messes up the visible output.

Filter and search

Every list endpoint accepts query parameters that match the resource fields: substring on strings, exact match on enums.

curl -sS -H "Authorization: Bearer $TOKEN" \
     "$API/users?email=avani&status=active" | jq

curl -sS -H "Authorization: Bearer $TOKEN" \
     "$API/todos?status=completed&page=1" | jq '.[].title'

Fetch a single record

curl -sS -H "Authorization: Bearer $TOKEN" "$API/users/4521" | jq

# Show only the fields you care about
curl -sS -H "Authorization: Bearer $TOKEN" "$API/users/4521" \
     | jq '{id, email, status}'

Create a record

The -d flag sets the body. Combined with -H "Content-Type: application/json", you have a full POST. Capture the new id with jq -r if you need it for follow-up calls:

NEW_ID=$(curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Avani Iyer",
    "email": "avani-'$(date +%s)'@example.com",
    "gender": "female",
    "status": "active"
  }' \
  "$API/users" | jq -r '.id')

echo "Created user $NEW_ID"

Update and delete

PATCH is partial, PUT is full replace, DELETE returns 204. Note the -i flag to keep the response headers so you can check the status code:

curl -sSi -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}' \
  "$API/users/$NEW_ID"

curl -sSi -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "$API/users/$NEW_ID"

Inspect headers

Pagination metadata, rate-limit budget, and simulation flags are all in headers, not the body. Use -D - to dump them to stdout, or -I for a HEAD request that fetches only the headers:

curl -sS -D - -o /dev/null -H "Authorization: Bearer $TOKEN" \
     "$API/users" | grep -i 'x-pagination\|x-ratelimit'

# Just the headers, no body
curl -sSI -H "Authorization: Bearer $TOKEN" "$API/users"

Test loading and error states

Two query parameters let you simulate slow responses and forced errors without changing the endpoint. ?delay=N pauses for N milliseconds (up to 5000), and ?force_status=N returns the named status code so you can check your error path. The simulation is announced via X-Simulated-Delay-Ms and X-Simulated-Status:

# Fake a 2-second slow response
time curl -sS -H "Authorization: Bearer $TOKEN" \
          "$API/users?delay=2000" > /dev/null

# Fake a 503
curl -sSi -H "Authorization: Bearer $TOKEN" \
     "$API/users?force_status=503"

Save and load presets

If you call the same endpoints from your shell again and again, write them as small functions in your .zshrc or .bashrc. Saves a lot of retyping:

function gorest() {
  curl -sS -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" "$@"
}

gorest "$API/users?status=active" | jq '.[].email'
gorest -X POST -d '{"name":"X","email":"x@e.io","gender":"male","status":"active"}' \
       "$API/users" | jq

Tips

• Use -w '%{http_code}' to print the status code at the end of the response. Useful in scripts that branch on success vs failure.
• When the response is huge, pipe through jq -C for colour, then less -R to scroll without losing colour.
• Add .json or .xml to any URL to switch the response format. "$API/users.xml" returns XML.
• curl -k disables certificate verification. Never enable it permanently. If you hit cert errors against this API, the cert chain is fine; your local trust store needs updating.