Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

An API URL is the web address an HTTP client uses to locate an API resource or operation. In a request such as GET https://api.example.com/users/42?expand=orders, the URL identifies where the request goes. The HTTP method, headers, optional body, authentication, and response rules determine what the server does and how it answers.

Understanding that distinction prevents common bugs: treating a query parameter as a path, omitting the API version, encoding an identifier incorrectly, or assuming that a URL alone completely describes an endpoint.

What an API URL contains

Most HTTP API URLs follow the generic URI form scheme://authority/path?query#fragment. The query and fragment are optional. A typical API request is:

GET https://api.example.com/users/42?expand=orders

Here is what each part means:

Part Example Purpose in an API request
Scheme https Selects the access protocol. Production APIs normally use HTTPS so credentials and data are encrypted in transit.
Authority api.example.com Identifies the server. It can also include a port, such as api.example.com:8443.
Path /users/42 Expresses the resource hierarchy. Here, 42 identifies one user.
Query ?expand=orders Adds optional instructions or filters without changing the basic resource path.
Fragment #details Usually has no role in an HTTP API call: browsers use it locally, and it is normally not sent to the server.

The URL is the locator. It is not the whole request. A server also needs the method (GET, POST, PUT, PATCH, or DELETE), headers, authentication, body format, and expected response contract.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

URL versus endpoint

Use URL for the address string. Use endpoint for the callable interface formed by an address plus its method and contract.

For example, these are different endpoint operations even though they share a URL:

GET    https://api.example.com/users/42
PATCH  https://api.example.com/users/42

The first might retrieve a user; the second might update it. The URL alone cannot tell a client which operation to perform. Endpoint documentation should state:

  • the HTTP method and complete URL pattern;
  • required path and query parameters;
  • authentication and required headers;
  • the request body schema, when applicable;
  • success and error response formats, status codes, and pagination behavior.

Path, path parameters, and query parameters

Path hierarchy identifies the resource

Paths commonly model collections and members:

/accounts/7/projects/18/keys

This reads as the keys collection belonging to project 18, which belongs to account 7. A value embedded in the path is a path parameter. It usually identifies which resource is being addressed and is required for that URL pattern.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Queries modify retrieval

Query parameters commonly filter, sort, paginate, expand, or otherwise tune a request:

GET https://api.example.com/orders?status=paid&limit=25&cursor=abc123

The path selects the orders collection; the query asks for paid orders, limits the page size, and supplies a cursor. Whether a parameter is required, repeatable, or accepted with an empty value is defined by that API, not by URL syntax alone.

Do not move parameters between locations casually

/users/42 and /users?id=42 are different URL designs. A server may implement only one. Follow the endpoint specification rather than guessing from naming conventions.

URL, URI, and endpoint: the practical difference

A URI (Uniform Resource Identifier) is the broad category of strings that identify resources. RFC 3986 describes a URI as a simple, extensible way to identify a resource. A URL is the commonly used URI form that also indicates how to locate the resource through an access mechanism. In everyday web development, “URL” is the normal term for an HTTP web address.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

An endpoint is an API concept rather than merely a string type: it is the server operation a client invokes at a particular URL with a particular method and contract. Consequently:

  • Every API URL can be discussed as a locator.
  • A URL can represent multiple operations when methods differ.
  • An endpoint description is incomplete if it lists only a URL and omits method, parameters, authentication, or schemas.

Absolute and relative API URLs

Absolute URLs

An absolute URL includes its scheme and authority:

https://api.example.com/v1/reports?from=2026-01-01

Use absolute URLs when a client can call multiple hosts, when configuration is external to a browser page, or when logging a request unambiguously.

Relative URLs

A relative URL omits some or all of the base:

/v1/reports?from=2026-01-01
reports/2026

A URL library resolves it against a base URL. For example, resolving /v1/reports against https://api.example.com/app/ produces https://api.example.com/v1/reports. A relative URL without a leading slash, such as reports/2026, is resolved relative to the base path and can produce a different result.

Relative URLs are useful inside a browser application that already has a known origin. Server-side jobs, webhooks, configuration files, and cross-environment clients are usually clearer and safer with an explicit base URL.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

How an API client builds and sends a URL

  1. Choose the base URL. Keep development, staging, and production hosts in configuration rather than scattering them through code.
  2. Append the documented path. Insert path parameters only after validating their type and encoding them as one path segment.
  3. Encode query values. Use a URL or query-builder library instead of concatenating user input.
  4. Set the method and headers. Add authentication, Accept, and, for a body, the appropriate Content-Type.
  5. Send and inspect the response. Record the final URL (without secrets), status code, response headers, and structured error body.

JavaScript URL handling

const base = new URL('https://api.example.com/v1/');
const url = new URL('users/42', base);
url.searchParams.set('expand', 'orders');

const response = await fetch(url, {
  method: 'GET',
  headers: { 'Accept': 'application/json' }
});

if (!response.ok) {
  throw new Error(`API returned ${response.status}`);
}
const user = await response.json();

The URL and URLSearchParams classes parse, normalize, resolve, and encode components. They also avoid errors caused by spaces, ampersands, Unicode, or repeated parameters.

Python URL handling

from urllib.parse import urlencode, urljoin
import requests

base = "https://api.example.com/v1/"
path = "users/42"
params = {"expand": "orders", "limit": 25}
url = urljoin(base, path)
response = requests.get(url, params=params, timeout=30)
response.raise_for_status()
user = response.json()

requests encodes the query mapping and exposes the final URL as response.url, which is useful when diagnosing encoding or redirect issues.

Encoding, normalization, and security details

Encode each component for its context

Path and query components have different rules. An identifier containing a slash may need percent-encoding so the server treats it as one path segment rather than a nested path. Query values containing &, +, spaces, or non-ASCII characters must also be encoded correctly. Do not apply an entire-URL encoder to a string that already contains separators, or you may encode the separators themselves.

Normalize carefully

Case, trailing slashes, percent-encoding, duplicate query keys, and default ports can affect routing, caching, signatures, and access control. Normalize only according to the API’s documented rules. A client that changes a signed URL after signing it can invalidate the signature.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Keep secrets out of URLs

Query strings can appear in browser history, reverse-proxy logs, analytics systems, referrer headers, and monitoring data. Prefer an authorization header such as Authorization: Bearer ... for credentials. If an API requires a key in the query, redact it from logs and avoid sharing the complete URL.

Do not confuse a fragment with a server parameter

In a browser, everything after # is handled locally and is generally not transmitted in the HTTP request. Put server-side filters and identifiers in the path or query as the API specifies.

Versioning and environment design

APIs commonly distinguish versions in the host (https://v2.api.example.com), path (/v2/), or headers. The location is a design choice; the important requirement is consistency and clear documentation. Keep the version in one configurable base URL so upgrading does not require editing every call.

Likewise, staging and production should use explicit hosts or configuration values. Never infer an environment by string replacement in arbitrary URLs. Validate the resulting host before sending credentials.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Common URL and endpoint failures

Symptom Likely cause Fix
404 Not Found Wrong path, version, host, or trailing-slash rule. Compare the final URL with the documented route and confirm the environment.
405 Method Not Allowed The URL exists but does not support the chosen HTTP method. Use the method documented for that endpoint.
400 Bad Request Malformed encoding, missing parameter, invalid value, or unexpected query name. Log the encoded URL safely and validate each parameter against the schema.
401 Unauthorized Missing, expired, or malformed credentials. Send the required authentication header and check token scope and expiry.
403 Forbidden Credentials are valid but lack permission, or the server blocks the request origin. Check scopes, account permissions, IP policy, and required headers.
Request works in a browser but not in code Browser cookies, redirects, headers, or a relative URL supplied context that the script lacks. Use an absolute base URL and reproduce only the headers and cookies the API actually requires.
Signature mismatch The URL was normalized or encoded differently before verification. Sign the exact canonical method, path, query ordering, and encoding required by the provider.
Unexpected duplicate or missing filters Repeated query keys were collapsed or concatenated incorrectly. Use a query library that supports arrays and confirm the API’s repeated-key convention.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Reliability, performance, and observability

  • Reuse HTTP connections where your client supports pooling; repeated DNS and TLS setup adds latency.
  • Set connect and total timeouts. A URL that is valid can still point to a slow or unavailable service.
  • Retry only transient failures such as selected network errors or documented 429/5xx responses. Use exponential backoff and an idempotency key for retryable writes.
  • Cache only responses the API permits you to cache. Query strings often distinguish representations, so include the complete normalized URL in cache keys.
  • Log method, host, path, status, duration, request ID, and a redacted query. Never log bearer tokens or sensitive personal data.
  • For paginated APIs, follow the provider’s next-page URL when supplied instead of reconstructing cursors yourself.

Using a URL to request a website screenshot

A screenshot API is a practical example of a URL being the input resource. The API URL is the service address; the target website URL is a parameter in the request. Keep those two URLs distinct. For a basic service call, encode the target URL as a query value:

GET https://api.example.com/screenshot?url=https%3A%2F%2Fexample.com

Do not paste an unencoded target containing its own query string into the outer URL by string concatenation; use a URL library or query option so the inner ? and & remain part of the target value.

Or skip the browser setup

ScreenshotNeo accepts a website URL with one API call and returns PNG, JPEG, WebP, or PDF. It accepts cookie and consent banners before capture, removes more than 60 known consent platforms plus newsletter popups and chat widgets, and lets you turn each cleanup step off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and whether the request was billed.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo documentation for the complete request contract. Options include full-page capture with lazy images, CSS-selector element capture, dark mode, device presets or custom viewports, retina scale, PDF paper settings and page ranges, custom CSS and JavaScript, clicks, selector or network-idle waits, ad and tracker blocking, custom headers/cookies/user agents, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Existing parameter names used by other screenshot APIs are also accepted, which can reduce migration work.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots, and every feature is available on every plan. Create a free ScreenshotNeo account to get started.

FAQ

Can one URL have more than one endpoint?

Yes. Different HTTP methods can expose different operations at the same URL, so identify the method as well as the address.

Is every URI a URL?

No. URI is the broader identification category; a URL is a URI that provides a locating mechanism. In normal HTTP development, the terms often overlap in casual usage.

Should API URLs end with a slash?

There is no universal rule. Follow the provider’s documented route because some servers, caches, and signature schemes treat slash and no-slash forms differently.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Can a URL contain a fragment in an API request?

A client may construct one, but browsers generally do not send the fragment to the server. Use a documented path or query parameter for server-side data.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.