DEV Community

Cover image for Debugging API JSON in the Browser: A Practical Workflow
Min Yi
Min Yi

Posted on

Debugging API JSON in the Browser: A Practical Workflow

#webdev

When an API response looks wrong, the problem is often not the endpoint itself. A missing field, an unexpected string, or a content-type mismatch can be hidden inside a large JSON payload. A repeatable browser-based workflow makes these issues much easier to isolate.

1. Capture the exact response

Start in your browser's Network panel. Reload the page, select the request, and inspect three things:

  • the request URL and query parameters
  • the response status and response headers
  • the raw response body

Do not rely only on the rendered UI. A frontend may silently ignore fields it cannot parse, while the Network panel shows the data that actually crossed the wire.

Check the Content-Type header as well. A JSON response should normally use application/json. If the server returns HTML or plain text with a 200 status, the real problem may be a proxy, authentication redirect, or server-side error page.

2. Format the payload before reading it

Minified JSON is difficult to inspect and easy to misread. Format it first so nested objects and arrays become visible. Then look for:

  • fields that are present in one item but absent in another
  • numbers returned as strings
  • null values where the client expects an object
  • duplicate keys
  • arrays that are empty because a filter was applied upstream

A formatter is most useful when it preserves the original value types and clearly reports invalid syntax. If formatting fails, copy the smallest failing fragment into a validator instead of guessing where the error is.

3. Compare the schema with the client

Many “API bugs” are contract mismatches. Compare the actual response with the interface your code expects.

For example, the client may expect:

{
  "total": 3,
  "items": [
    { "id": 42, "name": "Ada" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

But the server may return total as a string:

{
  "total": "3",
  "items": [
    { "id": 42, "name": "Ada" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

That difference can break sorting, arithmetic, or runtime validation even though the JSON is syntactically valid. Document the expected shape with TypeScript types or a schema validator, then validate at the boundary where data enters your application.

4. Check encoding and escaping

If a value contains a URL, Base64 string, Unicode text, or user-generated content, inspect encoding separately from structure. Common symptoms include:

  • plus signs or slashes changing after a round trip
  • spaces appearing where percent-encoding was expected
  • Unicode characters becoming replacement symbols
  • a token being decoded twice

Test the smallest representative value in both directions. This is faster than debugging the entire response and helps identify whether the issue is in the API, transport, or client code.

5. Reduce the failing case

Once you find a suspicious field, create a minimal JSON example containing only the relevant structure. A reduced case helps you answer three questions:

  1. Is the payload invalid JSON?
  2. Is it valid JSON with the wrong type or shape?
  3. Is the payload correct, but the application reading it incorrectly?

Keep the original response for reference, but use the reduced case in bug reports and tests. It makes the issue reproducible without exposing unrelated data.

6. A small browser toolkit can speed up the loop

You do not need a large local setup for every inspection task. A few focused browser utilities can help with formatting JSON, converting JSON to TypeScript, encoding URLs, testing regular expressions, and checking timestamps.

For example, Yaya Tools provides free browser-based utilities for these small jobs at yayatool.com. The useful part is not the branding; it is having quick, disposable tools available while you investigate a request. No installation or account is required.

7. Record the result

Finish by writing down the request, the observed response shape, the expected shape, and the fix. If the issue is a contract mismatch, update the API documentation or type definition so the same bug does not return later.

A good debugging workflow separates transport problems, syntax problems, schema problems, and application logic. Capture the raw response, format it, compare it with the expected contract, test encoding independently, and reduce the failure to a small reproducible example. That process turns a vague “the API is broken” report into a fixable technical issue.

Top comments (0)