application/x-www-form-urlencoded vs JSON: When to Use Each

Two Common Ways to Send Data

Web applications commonly send structured data as either application/x-www-form-urlencoded or application/json. Both are valid, but they solve different problems.

Form URL encoding represents data as key-value pairs:

name=Alice+Smith&city=S%C3%A3o+Paulo

JSON represents data as a structured document:

{"name":"Alice Smith","city":"Sao Paulo"}

How Form URL Encoding Works

application/x-www-form-urlencoded is the traditional format used by HTML forms. Names and values are encoded like query parameters. Spaces are often represented as +, and reserved characters are percent-encoded.

It is compact for simple key-value data and is still required by many OAuth, payment, and legacy API endpoints.

How JSON Works

JSON is better for nested data, arrays, typed values, and API payloads that need to represent more than flat strings. It can express numbers, booleans, null, arrays, and objects directly.

{
  "customer": {
    "name": "Alice Smith",
    "tags": ["trial", "newsletter"]
  }
}

Trying to represent this in form URL encoding is possible but less standardized.

When to Use Form URL Encoding

Use application/x-www-form-urlencoded when:

• Submitting a simple HTML form.
• Calling an API that explicitly requires it.
• Working with OAuth token endpoints.
• Sending small flat key-value payloads.
• Matching browser form behavior.

In JavaScript:

const body = new URLSearchParams();
body.set("grant_type", "client_credentials");
body.set("scope", "read:items");

fetch("/oauth/token", {
  method: "POST",
  headers: {"Content-Type": "application/x-www-form-urlencoded"},
  body
});

When to Use JSON

Use JSON when:

• The payload has nested objects or arrays.
• You need clear numeric or boolean values.
• You control both client and server.
• The API documentation asks for application/json.
• You need a readable request body for logs and debugging.

In JavaScript:

fetch("/api/orders", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
  body: JSON.stringify({quantity: 2, priority: true})
});

Encoding Differences

Form URL encoding applies percent-encoding rules to names and values. JSON does not percent-encode its own content; it uses JSON string escaping. If a JSON document is placed inside a URL parameter, then the entire JSON string must be URL encoded because it becomes URL data.

Security and Debugging

Neither format is secure by itself. Sensitive data needs HTTPS and appropriate server-side handling. Do not put secrets in query strings because URLs often appear in logs, browser history, and referrer headers.

For debugging, check the Content-Type header first. Many bugs happen when the body format and content type do not match.

Frequently Asked Questions

Is form URL encoding obsolete?

No. It remains common for HTML forms, OAuth, and many integrations. JSON is more flexible, but form URL encoding is still part of the web platform.

Can form URL encoding send arrays?

Yes, but conventions vary. Some systems use repeated keys, such as tag=a&tag=b. Others use bracket notation, such as tag[]=a&tag[]=b.

Should passwords be sent in query strings?

No. Use a POST body over HTTPS and follow the API's required format. Query strings can leak through logs and browser history.