A Review of URLs


It is common to come across the acronyms URL and URI used throughout technical literature. Part of the cause for confusion stems from how they seem to be used interchangeably.

URI, or uniform resource identifier, is a name used to identify a resource. The resources represented by URIs can be anywhere.

URL, or uniform resource locator, is a reference to a web resource that specifies its location on a computer network and a mechanism for retrieving it.

URIs are like social security numbers: every US citizen has a unique number, and as a result, these numbers could be used to reference specific individuals in a computer system (and in fact, they often are used for exactly this purpose in the medical and health insurance industry). But if you needed to have a face to face conversation with a person, just knowing their social security number would do little to tell you where to find them.

URLs, on the other hand, are like street addresses. Given the street address of a person, it is possible to actually find and interact with that person. These identifiers also uniquely identify a resource, which means that a URL is a kind of URI.

URLs also include how to access the resource. All the URLs we will be working with in this book (and that you'll work with on most projects) begin with http:// or https://, which signify the resource can be accessed using the HTTP protocol. When the scheme is https://, it is an HTTP connection over a secure connection.

When it comes to deciding to use URI or URL, the thing to remember is this: if you are working with resources on the internet, just use URL.

The Parts of a URL

URLs are made up of a few components:

  • A scheme, such as http
  • ://, a colon and two slashes
  • A hostname, usually a domain name such as blogs.com
  • An optional colon and port, such as :81
  • The path to the resource, such as /api/v1/pages/1
  • An optional query string, such as ?query=term

Put together, the example values above would construct the URL http://blogs.com:81/api/v1/pages/1?query=term. Ports are relatively uncommon in the URLs used when interacting with public APIs, and we won't go into them further.

This book will discuss a lot on URLs. It will also reference paths quite a bit, as they are shorter and make the relevant sections more obvious. If you have a full URL and need to know what its path is, just remove everything from the beginning to the end of the domain name, leaving the slash.

Identifiers in Paths

Some of the paths used in API documentation or when discussing APIs include identifiers for specific resources. Take, for example, the path /products/42. The final segment of the path, 42, is a value that is used to identify a specific product.

When referring to this path in the general sense and without a particular product in mind, it would be written /products/:id. The final segment, :id, is a placeholder for a value to be filled in later. Any value in a path that begins with a colon in this book should be considered a placeholder. Here are a few other examples:

  • /api/:version/products/:id
  • /api/v1/users/:id/profile

It is possible for paths to include multiple placeholders. If a product could have many comments, and the product's path was /products/:id, it is possible that an individual comment's path could be /products/:product_id/comments/:id. This form of path can be referred to as nested, because the route for comments, /products/:product_id/comments, is nested underneath the path for a product, /products/:id.

The specific placeholder used within a path isn't important as long as it is unique within the path. It is common for the final identifier to be named :id, while other placeholders have names prefixed with the resource they map to.


  • Working with web APIs involves working with URLs.
  • URLs represent where a resource is and how it can be accessed.
  • URLs typically contain a scheme, hostname, path, and sometimes a query string.
  • Paths (and URLs) can include placeholders when they are written generically.