API & webhooks

Pass Parameters to a REST API Without Breaking Their Meaning

Build REST query parameters with URLSearchParams, preserve repeated values and Unicode, and distinguish path, query, header, and body inputs.

By Uddhav Gopani, FounderPublished 27 September 2026Updated 29 September 2026

Put each input where the endpoint expects it

A REST request can carry values in path segments, the query string, headers or the body. These locations are not interchangeable. An identifier in /notes/7 selects a path resource, while a tag query filters a collection. Follow the endpoint contract before deciding how to serialize a value.

AJAX changes how the browser performs the request, not the meaning of those parameters. The same URL-building rules apply whether the request is sent with fetch or XMLHttpRequest. Start with a URL object and let a dedicated query serializer handle reserved characters.

Build scalar and repeated query values deliberately

function notesUrl(base, query, tags, page) {
  if (typeof query !== "string" || !Array.isArray(tags)
      || !tags.every(tag => typeof tag === "string")) {
    throw new Error("Use a query string and an array of tag strings.");
  }
  if (!Number.isSafeInteger(page) || page < 1) {
    throw new Error("Page must be a positive safe integer.");
  }
  const url = new URL("/notes", base);
  url.searchParams.set("q", query);
  for (const tag of tags) url.searchParams.append("tag", tag);
  url.searchParams.set("page", String(page));
  return url;
}

For the query maps & walks and tags parks and rivers, this function creates one q value and two tag entries. Repeated parameters are an example API convention; another service may require a comma-separated value or a different format. Do not assume every server interprets repeated names identically.

The endpoint begins with a slash, so it resolves from the origin root. Passing a base URL ending in /v2/ does not preserve that prefix in this function. Use the route structure the API actually documents, and test the assembled URL instead of guessing from how the input string looks.

Avoid manual escaping and double encoding

URLSearchParams performs the query serialization. Supply the original text, including spaces, plus signs, ampersands and Unicode. If you first encode the value manually and then give it to this serializer, the encoded percent signs can be encoded again.

Compare decoded parameter values during tests rather than demanding one visual spelling for a space. Query serialization can use a plus sign for a space, while a literal plus needs its own encoding. Searching for a raw plus character in the URL is not a sufficient test that the original value survived.

Use set for a scalar value that should replace earlier entries of the same name, and append when the endpoint intentionally accepts repeated values. Accidentally appending the current page each time a user clicks Next can leave several page parameters with server-dependent interpretation.

Validate types before converting everything to text

A URL query contains strings, but the application's inputs can still have useful types before serialization. The example rejects a fractional page number, zero and an unsafe integer instead of quietly converting them into surprising request parameters.

Do not pass a nested object directly to a query serializer and expect a universal structured representation. Decide whether the endpoint wants repeated keys, a JSON-valued parameter or a request body. Also decide how it treats an omitted value, an empty string and the literal text null; those can mean different things.

Keep sensitive credentials out of ordinary query values

URLs can appear in logs, browser history and shared diagnostics. Use the API's documented authentication mechanism rather than adding a secret query parameter for convenience. Redact sensitive search values as well when saving a reproduction for support.

For a JSON POST body, use JSON serialization and the corresponding content type. Do not move a large or sensitive JSON document into the query string solely because a browser form was easier to build that way. The request's shape should follow the operation contract.

Verify the values the server actually receives

Test a query containing an ampersand, a literal plus, spaces and Unicode. Use getAll to assert repeated tag values and verify that page appears once. Reject invalid page values before sending the request. Then inspect a local fixture's parsed query to confirm the transport preserves those values.

The REST API Testing Tool can send the assembled URL to an authorized endpoint and display its readable response. A successful HTTP status alone does not prove the filters were interpreted correctly, so also compare the returned data with a known fixture.