HTTP URL (Uniform Resource Locator) Formatting

## What is a URL? A URL (Uniform Resource Locator) is the address of a unique resource on the internet. It's a key mechanism used by browsers to retrieve published resources, such as HTML pages, CSS documents, images, etc. Theoretically, each URL uniquely identifies a resource, however there are exceptions such as url shortners, redirects, or URLs that point to resources that no longer exist. These are some examples of URLs: `https://example.website.com` `https://example.website.com/en-US/docs/Learn_web_development/` `https://example.website.com/en-US/search?q=URL` ## URL Components URLs are made of components, some of which are optional, others necessary. We are going to go into an overview for what these components are. We are going to use this example URL: `http://www.example.com:80/path/to/myfile.html?key1=value1&key2=value2#SomewhereInTheDocument` ### Scheme The first part of the URL, indicating the protocol the browser has to use to request the resource. Usually for websites the protocol is HTTP or HTTPS, and it's typically seen in the URL as: `http://`. ### Authority The next component of the URL is the authority, which is separated from the scheme by the `://`. In our example this is `www.example.com:80`. The authority contains both the domain name `www.example.com` and the port number (optional) `80` separated by a colon. Note that typically the domain name is used, but it could also be an IP address. A good example of an authority is used for testing websites locally: `http://localhost:5000/`. ### Path to Resource The path to resource is basically like a file path to where that resource is on the server, in our example: `/path/to/myfile.html`. For this webpage for instance it's `/blog/http-url-uniform-resource-locator-formatting`. Note that this used to literally represent a physical file location on a web server, but now it's largely an abstraction. Typically for Path to Resources, we can use additional path segments to denote sub-resources or configuration steps, such as `/users/123/settings` where 123 is a user ID. This can also be generally denoted as `/users/{user_id}/setting`. Note that this is denoted as a *path parameter*. ### Parameters Typically extra parameters are a list of key/value pairs denoted after a ? and delimited by &'s. For example `?key1=value1&key2=value2` denotes the extra parameters key1=value1 and key2=value2 are being passed to the web server. This is typically used for the web server to perform extra tasks before returning the resource such as filtering or searching. Note that this is denoted as a *query parameter*. Some common examples and use cases of these parameters are: - Filtering: `/users?role=admin` - Sorting: `/users?sort=created_at` or `/users?sort=created_at` (*descending) - Pagination: - Page based: `/users?page=2&limit=20` - Cursor based: `/users?cursor=eyJpZCI6...` - Field selection: `/users?fields=id,name,email` - Including related resources: `/users?include=roles,permissions` Common query parameter formatting patterns are as follows: - Repeated Keys (common, mentioned), use & as delimiter - `/users?role=admin&role=editor` - Comma Separated Values - `/users?role=admin,editor` - Array Bracket Notation, common in PHP style systems - `/users?role[]=admin&role[]=editor` - JSON Encoded Parameter - `/search?filter={"age":{"gt":30}}` - If URL encoded, may look like: `/search?filter=%7B%22age%22%3A%7B%22gt%22%3A30%7D%7D` ### Anchor The anchor `#SomewhereInTheDocument` is an anchor to another part of the resource itself, i.e. a bookmark inside the resource. This gives the browser directions to show the content located at that bookmarked spot. Note that this anchor is only used client side and is not sent to the server.