ApiSkills

Foundations · 8 min

Anatomy of a URL

Every part of a web address — scheme, host, port, path, query — and the words people mix up: endpoint, resource, base URL.

Every API call starts with a URL (Uniform Resource Locator) — the address of the thing you want. It looks like one long string, but it is really several labelled parts. Knowing each part by name is what lets you read any API's documentation.

The parts of a URL

https://api.example.com:443/v1/orders/42?status=open&page=2#details
\___/   \_____________/\_/\___________/\_______________/\_____/
scheme       host      port    path          query      fragment
PartExampleWhat it is
Scheme / protocolhttpsHow to talk. https = HTTP over TLS (encrypted); http = plain text. APIs should always be https.
Hostapi.example.comThe server's domain name, resolved to an IP address by DNS.
Port443Which "door" on the server. Defaults are implied — 443 for https, 80 for http — so you rarely type it.
Path/v1/orders/42Which resource on that server. Read left-to-right as a hierarchy: version → collection → a specific item.
Query string?status=open&page=2Options after a ?, as key=value pairs joined by &. Filtering, sorting, pagination.
Fragment#detailsA pointer within a page. Handled by the browser and never sent to the server.

The words people mix up

  • Base URL — the fixed front part you configure once: https://api.example.com. Everything else hangs off it.
  • Endpoint — a specific path that does one job: /v1/orders. "The orders endpoint."
  • Resource — the thing an endpoint exposes: an order, a customer, a candle. /v1/orders/42 is the resource "order 42".
  • Path (or route) — the part after the host that selects the resource.
  • Absolute vs relative — an absolute URL is the whole thing (https://.../v1/orders); a relative path is just /v1/orders, joined onto the base URL. APIs often hand you a relative "next" link you must join to the base yourself.

Path parameters vs query parameters

Two different ways to pass values, and confusing them is a common bug. A path parameter identifies WHICH resource and is part of the path. A query parameter modifies the request and comes after the ?. Rule of thumb: path = which thing, query = how you want it.

GET /v1/orders/42            # path param 42  -> one specific order
GET /v1/orders?status=open   # query param    -> filter the collection

Safe characters and encoding

URLs may only contain a limited set of characters. Spaces, &, ?, =, and non-English letters must be percent-encoded — a space becomes %20, an ampersand %26. Most tools do this for you, but when a value with a space or symbol "breaks the URL", missing encoding is usually why.

?q=annual report   ->  ?q=annual%20report
?name=A&B Corp     ->  ?name=A%26B%20Corp

Tip · When you meet a new API, find its base URL first, then its list of endpoints, then the path vs query parameters each one takes. That is 80% of understanding an API before you send a single request.