How to Use JSON Formatter to Debug API Responses

A practical guide to reading, formatting, and validating JSON data returned by REST APIs — with real command-line examples and common pitfalls explained.

Why JSON Formatting Matters

When you fetch data from a REST API, the raw response is typically a compact, single-line blob of JSON — intentionally minified to reduce bandwidth. While this is efficient for machines, it is nearly unreadable for humans. A single API response can contain hundreds of nested keys, arrays, and objects all crammed onto one line.

A JSON formatter (also called a JSON pretty-printer) takes that compressed output and reformats it with consistent indentation, line breaks, and syntax highlighting. This transforms something unreadable into a structured, scannable document where you can immediately spot missing fields, unexpected nulls, or wrong data types.

Debugging without formatting is like reading a minified JavaScript bundle without a source map — technically possible, but an unnecessary waste of your time and cognitive energy.

Step 1: Fetch an API Response with curl

The most common way to hit an API from the terminal is with curl. Here is a basic request to a public JSON API:

curl https://jsonplaceholder.typicode.com/posts/1

The raw output looks like this:

{"userId":1,"id":1,"title":"sunt aut facere repellat provident","body":"quia et suscipit\nsuscipit recusandae..."}

Not very readable. Let's fix that.

Step 2: Pipe Through jq for Instant Formatting

jq is the gold standard for JSON processing in the terminal. Install it with sudo apt install jq (Debian/Ubuntu) or brew install jq (macOS). Then pipe your curl output through it:

curl -s https://jsonplaceholder.typicode.com/posts/1 | jq .

The . is the identity filter — it outputs the entire document, formatted. Result:

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident",
  "body": "quia et suscipit\nsuscipit recusandae..."
}

Immediately you can see all four fields, their types, and their values at a glance.

Step 3: Extract Specific Fields

jq is not just a formatter — it is a full query language for JSON. To extract just the title field:

curl -s https://jsonplaceholder.typicode.com/posts/1 | jq '.title'

To extract multiple fields into a new object:

curl -s https://jsonplaceholder.typicode.com/posts/1 | jq '{id: .id, title: .title}'

For arrays, use .[] to iterate and .[] | .title to extract a field from each element:

curl -s https://jsonplaceholder.typicode.com/posts | jq '.[0:3] | .[].title'

Step 4: Debug Authentication Headers

Many APIs require authentication headers. Use -H to pass them, and add -v (verbose) to see the full request/response cycle including status codes:

curl -s -v \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.example.com/users/me | jq .

The verbose flag shows the HTTP status line (HTTP/1.1 401 Unauthorized vs 200 OK), which is crucial when your token may be expired or malformed.

Step 5: Use the Browser DevTools JSON Viewer

If you are debugging API calls from a web app, the browser's Network tab in DevTools automatically formats JSON responses. Open DevTools (F12), go to the Network tab, make a request, click the entry, and select the Response or Preview sub-tab. Most modern browsers syntax-highlight and collapse nested objects for easy exploration.

For even more power, the JSON Viewer browser extension adds copy buttons, search, and path display for every JSON value — you can click any key to copy its full path like data.users[3].email.

Common Pitfalls When Debugging JSON APIs

Pitfall 1: Content-Type Mismatch

If the API returns Content-Type: text/html instead of application/json, you may be hitting an error page (like a 404 HTML page) instead of the API. Always check the response headers:

curl -s -I https://api.example.com/endpoint

Pitfall 2: Escaped Unicode Characters

Some APIs return escaped unicode like é instead of é. To decode them with jq, use the -r (raw output) flag or the @text filter. The online JSON formatter at Dev Toolbox automatically decodes unicode for display.

Pitfall 3: Trailing Commas

Standard JSON does not allow trailing commas after the last item in an object or array. If you hand-wrote or copy-pasted JSON and it fails to parse, look for trailing commas — they are the most common syntax error in manually written JSON.

Pitfall 4: Numbers as Strings

APIs sometimes return numeric IDs as strings ("id": "12345") instead of integers ("id": 12345). This breaks type comparisons in your code. Use jq 'type' on a field to verify its JSON type:

curl -s https://api.example.com/user/1 | jq '.id | type'

Using Dev Toolbox's Online JSON Formatter

For quick one-off formatting without installing anything, paste your raw JSON into the Dev Toolbox JSON Formatter. It provides instant formatting, syntax highlighting, error detection with line numbers, and a minify button to compress JSON back for use in code. It works entirely in your browser — no data is sent to any server.

Summary

Good JSON formatting habits save significant debugging time. Use curl | jq . for terminal work, browser DevTools for frontend debugging, and the Dev Toolbox JSON Formatter for quick online validation. The key insight is that formatted JSON reveals structure — and structure reveals bugs.

Related Tools & Snippets