Skip to main content

Protocol workflow

Reviewed

Use the HTTP and URL APIs as a debugging toolkit

A standards-grounded workflow for canonical URLs, method and status references, Accept negotiation, registered fields and browser CORS diagnostics.

The task
Turn a pasted URL and an HTTP exchange into a reproducible diagnostic without claiming to contact, secure or validate the remote service.
Review state

Direct answer

Direct answer

Start with URLs to canonicalize or resolve the address, use the IANA-backed method, status and field registries to inspect protocol vocabulary, then evaluate Accept or CORS with the dedicated compute endpoint. These tools operate on values you supply; they do not fetch the origin, verify reachability or prove that a server behaves as described.

Decision support

Choose the route by the job

When you need Choose Why
Parse an absolute URL or resolve a relative reference /urls It uses the WHATWG algorithm and returns canonical components and ordered query pairs without network access.
Look up registered request-method semantics /http-methods It mirrors the IANA method registry's safe and idempotent properties rather than inferring behavior from a name.
Look up a registered HTTP status /http-statuses It exposes the pinned IANA registry row and reference; an unknown code is an honest 404.
Check whether a field name is registered /http-fields It searches and looks up the pinned IANA HTTP Field Name Registry, including status metadata.
Parse or choose from an Accept field /content-negotiation It handles q weights, wildcards, parameters, specificity and explicit server-order tie-breaking.
Explain browser preflight or CORS rejection /cors-preflight It evaluates supplied request and response configuration against the Fetch CORS protocol and names the failed step.
01

What should you normalize before debugging HTTP?

Normalize the address first, but preserve the parsed evidence. Canonical serialization can change the visible URL while ordered duplicate query pairs remain semantically important to the application.

The URLs /parse route accepts one absolute URL. It canonicalizes the host, IDN spelling, IPv6 form and default port according to the platform's WHATWG URL implementation, and returns the query as ordered name/value pairs so q=one&q=two does not collapse into a map. /resolve performs the standard relative-reference operation against an absolute base.

This is syntax and resolution, not a network check. The endpoint does not make DNS requests, open a connection, follow redirects, inspect TLS or decide whether a destination is trustworthy. Canonical equivalence also does not imply application equivalence: a server can attach its own meaning to path spelling and duplicate query fields.

02

How do you distinguish registry facts from server behavior?

Use IANA-backed endpoints for the registered vocabulary, then treat the observed server exchange as separate evidence. Registry metadata describes the method, status or field—not whether one deployment implements it correctly.

HTTP Methods exposes the IANA registry's safe and idempotent flags. HTTP Statuses exposes assigned status codes and their defining references. HTTP Fields covers the registered field-name inventory. These are useful for validation, documentation and tooling, but a registered method can still be mishandled by a server and a known status code can still be returned in the wrong situation.

Keep that boundary in test output. Record the registry fact, the actual request and response, and your application-level expectation as three separate layers. That prevents a lookup tool from becoming a false production-health verdict.

  1. 01

    Parse the URL

    Save the canonical href plus the structured host, path and ordered query pairs. Reject credential-bearing URLs before logging or sharing them.

  2. 02

    Look up protocol vocabulary

    Use the method, status and field registries for assigned names, flags and defining references.

  3. 03

    Evaluate the negotiated representation

    Supply both the Accept field and the concrete media types your server can produce; inspect the controlling range and q value.

  4. 04

    Evaluate CORS separately

    Describe the cross-origin request and the response allow configuration. CORS is a browser read-permission protocol, not authentication or server-to-server access control.

03

Why separate content negotiation from CORS?

Accept chooses a representation; CORS controls whether browser JavaScript can read a cross-origin response. A successful answer to one says nothing about the other.

Content Negotiation /select considers q weights, wildcard specificity, media parameters and the supplied client/server order. It can correctly select application/json even if the eventual browser request would be blocked by CORS. Conversely, permissive CORS headers do not guarantee that the requested representation exists or that an endpoint returns a successful status.

CORS Preflight never contacts the origin. /preflight decides whether the supplied cross-origin request shape triggers an OPTIONS round trip. /check evaluates the allow-origin, method, header, credential and exposed-header values you provide. It names the failed Fetch step, but it cannot detect a reverse proxy that emits different headers in production.

  • The canonical URL and original input are both retained for diagnosis.
  • Duplicate query fields remain ordered instead of being coerced into a single-value object.
  • Registry facts are not presented as proof of a remote server's behavior.
  • Accept selection and browser CORS permission are tested as separate decisions.
  • No tool result is described as DNS, TLS, reachability, security or authentication validation.

Working requests

Run the concrete examples

Canonicalize a URL without losing duplicate query fields

Applies the WHATWG URL parser to an absolute URL, removes the default HTTPS port and preserves ordered duplicate query pairs in the parsed result.

curl request 
curl -s 'https://randomapi.dev/api/urls/parse?url=https%3A%2F%2Fexample.com%3A443%2Fdocs%3Fq%3Done%26q%3Dtwo%23api'

Inspect the response

  • href is the canonical https://example.com/docs?q=one&q=two#api serialization.
  • query contains q=one followed by q=two in the original order.
  • hasCredentials is false for this input.

Select a representation from an Accept field

Parses the RFC 9110 media ranges and deterministically selects from the concrete representations supplied by the caller.

curl request 
curl -s 'https://randomapi.dev/api/content-negotiation/select?accept=application%2Fjson%2Ctext%2Fhtml%3Bq%3D0.8&available=text%2Fhtml%2Capplication%2Fjson'

Inspect the response

  • selected is application/json for this request.
  • matchedRange is application/json with q=1.
  • The controlling quality value is 1.
  • available preserves text/html before application/json for the final tie-break.

Material limits

Caveats that change the decision

  • The URL tools parse supplied strings only. They do not fetch, resolve DNS, validate certificates, follow redirects or judge whether a destination is safe.
  • IANA registration and standards semantics do not prove that a particular server honors a method, field or status correctly.
  • Content Negotiation implements a bounded deterministic selection over the values supplied; it is not a proxy for framework-specific negotiation behavior.
  • CORS affects browser access to a response. It is not authentication, CSRF protection, network isolation or a server-to-server permission system.

Endpoint reference

APIs used in this guide

URL parser and resolver

/api/urls
REAL DATA

Parse absolute URLs or resolve relative references with the WHATWG URL algorithm — canonical hosts, ordered query pairs and no credential leakage.

Open endpoint reference

HTTP methods

/api/http-methods
REAL DATA

The complete current IANA HTTP Method Registry with safe and idempotent flags — filter the list or look up one canonical method token.

Open endpoint reference

HTTP status codes

/api/http-statuses
REAL DATA

The complete IANA HTTP status code registry with practical descriptions, defining RFCs and a retryable flag — list by category or look up a single code.

Open endpoint reference

HTTP field name registry

/api/http-fields
REAL DATA

Complete pinned IANA HTTP field-name registry with status, Structured Field type, references, search and case-insensitive lookup.

Open endpoint reference

HTTP content negotiation

/api/content-negotiation
REAL DATA

Parse RFC 9110 Accept media ranges and deterministically select the best available representation using specificity, parameters and q weights.

Open endpoint reference

CORS Preflight & Check API

/api/cors-preflight
REAL DATA

Explain whether a cross-origin request needs a preflight and whether the browser would allow the response, naming the exact Fetch step that failed.

Open endpoint reference

Visible provenance

Sources used by this guide