How to Parse and Analyze a URL

When you are debugging a redirect chain, validating OAuth callback URLs, or trying to figure out why a query parameter is not reaching your server, the first step is to break the URL into its pieces and inspect each one. The URL parser does this instantly, highlighting encoding issues and malformed components that are easy to miss when staring at a long string.

Understanding URL anatomy

A full URL contains up to seven distinct parts:

https://user:pass@api.example.com:8080/v2/users?role=admin&active=true#section-3
\___/   \_______/ \_______________/ \__/ \______/ \____________________/ \_______/
scheme  authority     hostname      port   path      query string        fragment

The scheme (https) tells the client which protocol to use. The authority can include credentials (rarely used today and generally discouraged). The hostname identifies the server, the port overrides the default for that protocol, and the path routes the request to a specific resource. The query string carries key-value parameters, and the fragment (hash) is handled entirely client-side and never sent to the server.

Percent-encoding (also called URL encoding) is required for characters that have special meaning in URLs or are not allowed in certain positions. A space becomes %20, an ampersand becomes %26, and a forward slash in a query value becomes %2F. When encoding goes wrong, parameters get split in unexpected places or values arrive garbled on the server.

The distinction between relative and absolute URLs matters in web applications. An absolute URL includes the scheme and hostname, while a relative URL like /api/users inherits them from the current page. Mixing these up can cause issues when your app runs behind a reverse proxy or on a different port in development versus production.

Tips and best practices

• Always encode user-supplied values. If a query parameter value can contain special characters (names, search terms, file paths), run it through encodeURIComponent() in JavaScript or the equivalent in your language. Never concatenate raw user input into a URL string.
• Use the URL constructor for parsing in code. In JavaScript, new URL(string) gives you a parsed object with .hostname, .pathname, .searchParams, and other properties. This is safer and more reliable than regex.
• Be careful with trailing slashes. /api/users and /api/users/ may route to different endpoints depending on your server framework. Be consistent.
• Check for double-encoding. If you see %2520 in a URL, the %25 is a percent sign, meaning the value was encoded twice. This usually indicates that an encoding function was called on an already-encoded string.

Troubleshooting

• Query parameter is missing on the server: The parameter might contain an unencoded & or =, causing the parser to split it into separate keys. Inspect the raw URL in the parser to see how the query string is being segmented.
• Fragment value is always empty server-side: This is expected behavior. The fragment (everything after #) is never sent in the HTTP request. If you need to pass that data to the server, move it into a query parameter.
• Redirect URL is rejected by OAuth provider: OAuth providers require exact URL matching. Even a trailing slash difference or a port number mismatch (localhost:3000 vs localhost:5173) will cause the redirect to be denied. Parse both the registered URL and the actual callback URL to compare them component by component.