How to Use JSON in REST APIs

JSON is the lingua franca of REST APIs. Nearly every modern web API sends and receives data in JSON format. This guide explains how JSON fits into the REST architecture, covering headers, request bodies, response structures, and practical tips for working with API data.

JSON in HTTP Requests

When sending data to an API (POST, PUT, PATCH requests), you include JSON in the request body and set the Content-Type header to application/json. This tells the server how to parse the incoming data.

POST /api/users HTTP/1.1
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "developer"
}

JSON in HTTP Responses

API responses typically include JSON in the body with a Content-Type: application/json header. The response structure usually follows conventions like wrapping data in a top-level object with metadata.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": 1,
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Common API Response Patterns

Well-designed APIs follow consistent JSON response patterns. Here are the most common structures you'll encounter:

• Single resource — undefined} wraps the object
• Collection — undefined includes pagination
• Error response — undefined}
• Envelope pattern — undefined} includes status

Debugging API Responses

API responses often come minified (no whitespace) to save bandwidth. To read them, paste the response into PureJSON's JSON Viewer to get a formatted, navigable tree view. For TypeScript projects, use the JSON to TypeScript converter to generate type definitions from sample API responses.

When comparing API responses between environments (staging vs production) or before/after a code change, the JSON Diff tool highlights exactly what changed.

Best Practices for JSON APIs

Follow these conventions when designing or consuming JSON APIs:

• Use camelCase for JSON property names (most common convention)
• Always set the Content-Type: application/json header
• Use ISO 8601 format for dates: "2024-01-15T10:30:00Z"
• Return consistent error responses with meaningful error codes and messages
• Use pagination for large collections to avoid sending too much data at once

Try These Tools

• JSON Viewer
• JSON → TypeScript
• JSON Diff

Frequently Asked Questions