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.
URLs are made up of a few components:
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.
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.