How to Format JSON for REST APIs

What is JSON?

JSON (JavaScript Object Notation) is a lightweight data interchange format that is easy for humans to read and write, and easy for machines to parse and generate. It has become the de facto standard for data exchange in modern REST APIs, replacing XML in most modern applications.

Despite its simplicity, poorly formatted JSON is one of the most common sources of bugs in API integrations. A single missing comma or mismatched bracket can cause an entire API request to fail silently. This guide covers the essential best practices for keeping your JSON clean, consistent, and error-free.

Why Formatting Matters

When working with REST APIs, JSON formatting is not just about aesthetics — it has real implications:

• Readability: Well-formatted JSON makes code reviews and debugging significantly easier.
• Consistency: A standard formatting style across your team reduces cognitive load.
• Error Prevention: Proper indentation reveals structural issues immediately.
• Tooling Compatibility: Linters and validators work best with consistently formatted JSON.

Best Practices

1. Use Consistent Indentation

The most common convention is 2-space or 4-space indentation. Pick one and stick with it across your entire project. Most formatters default to 2 spaces:

{
  "id": 1,
  "name": "AnsaTools",
  "description": "Free developer tools"
}

2. Use camelCase for Property Names

While JSON doesn't enforce a naming convention, camelCase is the most widely adopted standard in JavaScript-based APIs. Avoid snake_case unless your backend framework requires it (e.g., Python/Django APIs often use snake_case).

// ✅ Good
{ "firstName": "John", "lastName": "Doe" }

// ❌ Avoid mixing styles
{ "first_name": "John", "LastName": "Doe" }

3. Always Use Double Quotes

The JSON specification requires double quotes for both keys and string values. Single quotes or unquoted keys are valid in JavaScript objects but are not valid JSON and will cause parsing errors.

4. Avoid Trailing Commas

Unlike JavaScript, JSON does not allow trailing commas after the last element of an array or object. This is one of the most common sources of SyntaxError when manually editing JSON.

// ❌ Invalid JSON — trailing comma
{
  "name": "AnsaTools",
  "version": "1.0",  ← trailing comma!
}

// ✅ Valid JSON
{
  "name": "AnsaTools",
  "version": "1.0"
}

5. Use Null Instead of Empty Strings

When a field has no value, use null rather than an empty string "". This makes the intent clear — the value is absent, not just empty.

Common Pitfalls

• Forgetting to escape special characters like backslashes and double quotes inside strings.
• Using JavaScript comments (//) — JSON does not support comments.
• Sending unquoted numbers where strings are expected (e.g., zip codes like 01234).
• Nesting data too deeply — try to keep nesting to 3-4 levels maximum for readability.

Minified vs. Pretty-Printed JSON

In production APIs, JSON is typically sent minified (no whitespace) to reduce bandwidth. During development and debugging, pretty-printedJSON with proper indentation is essential for readability. Use a formatter to switch between the two effortlessly.