Anatomy of URL part 1

Protocol

In our URL, the protocol is https://.

The World Wide Web, the cornerstone of modern information exchange and communication, operates on a structured protocol known as HTTP, or Hypertext Transfer Protocol. At its core, HTTP is the language that web browsers and servers use to converse with each other, enabling the seamless retrieval and delivery of web content. While most of us interact with the web daily, the inner workings of HTTP methods and their significance remain a mystery to many.

In this chapter, we'll discuss the essential components of HTTP, with a primary focus on the pivotal role played by HTTP methods. Understanding these methods is not only crucial for web developers and programmers but also for technical writers looking to comprehend how data flows across the internet.

The Common HTTP Methods

HTTP methods, often referred to as HTTP verbs, are fundamental to the functioning of the World Wide Web. They define the actions that can be performed on resources, allowing clients (such as web browsers or applications) to communicate with servers in a structured manner. These methods are so crucial that they are often collectively referred to as CRUD operations, representing Create, Read, Update, and Delete actions on resources. In this section, we'll delve into the five primary HTTP methods: GET, POST, PUT, PATCH, and DELETE, each serving a specific purpose in web development and API design.

1. GET method

• Request: A GET request is used to retrieve data from the server. It typically doesn't have a request body, as it's meant for read-only operations. Any data needed for the request is usually sent as query parameters in the URL.
• Response: The response to a GET request contains the requested data. It may have a response body, such as JSON or HTML, depending on the resource being fetched.

2. POST method

• Request: A POST request is used to create a new resource on the server. It typically has a request body that contains data for the new resource.
• Response: The response to a POST request often includes information about the newly created resource. It may have a response body containing the ID or other details of the created resource.

3. PUT method

• Request: A PUT request is used to update an existing resource on the server. It typically has a request body that contains the complete updated representation of the resource.
• Response: The response to a PUT request often confirms the successful update and may include information about the updated resource.

4. PATCH method

• Request: A PATCH request is used to partially update an existing resource. It has a request body that contains a partial representation of the resource, indicating specific changes.
• Response: The response to a PATCH request confirms the successful partial update.

5. DELETE method

• Request: A DELETE request is used to request the removal of a resource from the server. It typically doesn't have a request body, as it's focused on resource deletion based on the URL.
• Response: The response to a DELETE request confirms the successful deletion.

6. Other HTTP Methods:

While the five primary HTTP methods (GET, POST, PUT, PATCH, DELETE) cover the majority of use cases in web development and API design, there are several other HTTP methods that serve specialized purposes. These less commonly used methods are valuable tools in specific scenarios. In this section, we'll explore some of these lesser-known HTTP methods and their unique roles.

1. HEAD Method

   Purpose: The HEAD method is similar to GET but without the response body. It is used to retrieve only the headers of a resource, providing metadata about the resource, such as its content type and length.

   The HEAD method is useful for checking resource availability or obtaining metadata without downloading the entire content.

2. OPTIONS Method

   Purpose: The OPTIONS method is used to request information about the communication options available for a resource. It retrieves details about the supported HTTP methods, headers, and other capabilities of the server.

   The OPTIONS method helps clients understand what actions they can perform on a resource.

3. TRACE Method

   Purpose: The TRACE method is primarily used for diagnostic purposes. It echoes the received request back to the client, allowing it to see how the request was modified by intermediaries (such as proxies or load balancers).

   TRACE can help in debugging and understanding the request-response flow.

4. CONNECT Method

   Purpose: The CONNECT method is used to establish a network connection to a resource, typically through a proxy server. It is often used for creating secure tunnels for encrypted communication, such as HTTPS.

   CONNECT is mainly used for setting up secure connections through proxy servers.

5. PATCH Method (RFC 5789)

   It's worth noting that there is a standardized PATCH method (as discussed earlier), but there's also an older version of PATCH defined in RFC 5789. The RFC 5789 PATCH method is less commonly used today, and the usage of the newer PATCH method is recommended for partial updates.

How to Identify a Protocol in a URL?

A URL (Uniform Resource Locator) consists of several components, and the protocol is one of them. It specifies how your browser or client should communicate with a web server to retrieve a resource. Here's how to identify the protocol in a URL:

1. Look at the Beginning of the URL: The protocol is indicated at the very beginning of a URL, right before the colon (:), and is followed by two slashes (//). For example:
   • HTTP protocol: http://www.example.com
   • HTTPS protocol: https://www.example.com
   • FTP protocol: ftp://ftp.example.com
2. Identify the Protocol Keyword: The protocol keyword (e.g., http, https, ftp) specifies the communication method or protocol to be used. It tells your browser or client how to connect to the server and what rules to follow for data exchange.
3. Understand the Purpose of the Protocol: Different protocols serve different purposes. For example:
   • HTTP (Hypertext Transfer Protocol) is used for standard web page access.
   • HTTPS (HTTP Secure) is a secure version of HTTP, encrypted for secure data transfer.
   • FTP (File Transfer Protocol) is used for transferring files to and from a server.
4. Note Any Secure Connections: If the URL begins with https:// instead of http://, it signifies a secure connection, indicating that data exchanged between the client and the server is encrypted.

In summary:

• HTTP methods that can have a request body: POST, PUT, PATCH
• HTTP methods that typically don't have a request body: GET, DELETE
• HTTP methods that can have a response body: GET, POST, PUT, PATCH
• HTTP methods that typically don't have a response body: DELETE

The specific details of request and response bodies may vary depending on the API and its design, but these examples provide a general understanding of how these HTTP methods are used.

Domain Name

In our URL, the domain name is www.google.com.

A domain is a website's internet address. It is the URL that you enter into your computer browser to see a website. For example, Google's domain is google.com, not https://www.google.com.

Top-level domains (TLDs) and second-level domains (SLDs) are the two types of domains. The top-level domain (TLD) is the last part of the domain, such as .com, .net, or .org. The SLD is the part of the domain that appears before the TLD, such as google in google.com.

How do domains work?

Imagine you're on a quest to explore the vast landscape of the internet.

Your trusty guide is your web browser. Whenever you decide to visit a website, here's what happens behind the scenes:

1. User's Request: You type "www.adventureland.com" into your browser.
2. DNS Request: Your browser asks the DNS server for the website's IP address.
3. DNS Lookup: The DNS server finds the IP address for "www.adventureland.com" (e.g., it's 192.168.1.1).
4. Browser's Journey: Your browser sails to the server at IP address 192.168.1.1.
5. Server Interaction: Your browser asks the server, "Show me www.adventureland.com."
6. Server Response: The server responds with the website's content.
7. Display: Your browser displays the website on your screen.

Domains in API documentation

Domains are important in API documentation because they identify the server that hosts the API. When you are using an API, you need to know the domain of the server to send requests to the API.

For example, the following URL shows the domain of the Google Search API:

https://developers.google.com/search/

The domain of the Google Search API is developers.google.com. This is the server that hosts the API, and it is the server that you need to send requests to in order to use the API.

Path

In our example URL, the path is /search?q=cats.

The path of a URL is the part of the URL that identifies the specific resource that is being accessed.

Paths can be simple or complex. They can be static or dynamic. Static paths are always the same, while dynamic paths can vary depending on the resource that is being accessed.

How do paths work?

Imagine you're using your web browser to search for adorable cat videos on Google. You type in your query, hit the search button, and magically, a list of cat videos appears on your screen. Ever wondered how this happens behind the scenes? It's all about how the web and APIs (Application Programming Interfaces) work together.

When you, the client, send a request to an API, you provide a URL, and the path within that URL is like a GPS coordinate for the data you want to access. Think of it as the address to your desired resource.

For instance, consider the URL: https://www.google.com/search?q=cats. In this case, the path is "/search?q=cats." This path serves as a set of instructions for Google's Search API server. It tells the server that you're on the hunt for information about "cats."

Now, the API server, like a diligent librarian, takes this path and scours its vast database for everything related to "cats." It gathers up a list of cat-related websites, images, and videos, and bundles them all up into a neat package. Finally, it sends this treasure trove of cat content back to your browser, which then displays it on your screen.

So, in a nutshell, when you send a request to an API, the path in the URL guides the API server to the right shelf in its digital library, where it fetches the data you desire and delivers it to your device, making your quest for cat videos as smooth as a purring kitten's fur.

Paths in API documentation

Paths are important in API documentation because they tell technical writers how to access the resources that are provided by the API. When writing API documentation, technical writers should clearly document the paths of all of the resources that are provided by the API.

For example, the following API documentation for the Google Search API shows the path of the resource that is used to search for a term:

GET /search?q={query}

The path of this resource is /search?q={query}, where {query} is a placeholder for the term that the user wants to search for.

How to Identify a Path in a URL?

To identify the path in a URL, follow these steps:

1. Locate the Domain: The domain is usually the first part of the URL, like "https://www.example.com."
2. Find the Slash (/) After the Domain: After the domain (and possibly port, if specified), there's typically a forward slash (/). The path starts after this slash.
3. Read the Path: The path consists of one or more segments separated by forward slashes (/). Each segment in the path represents a directory or resource on the web server.

For example, in the URL "https://www.example.com/products/electronics/laptops," the path is "/products/electronics/laptops."

Tips for Writing API Documentation for Paths:

• Use descriptive and consistent naming conventions for paths.
• Document the path parameters that are used in each path.
• Provide examples of how to use each path.
• Explain what each path returns.
• Link to other relevant API documentation, such as the documentation for the resources that are returned by each path.

Query Parameters in URLs

In our example URL, the query parameter is: q=cats.

Query parameters are key-value pairs in a URL that provide additional information to the web server when performing an HTTP request. They are often used in online applications and APIs to send data from the client to the server (typically a web browser or application). The query parameters are separated from the basic URL by a question mark ('?'), whereas they are divided by ampersands ('&').

How to recognize Query Parameters

• Look for the Question Mark ('?'): Query parameters are typically introduced in a URL using a question mark ('?'). This question mark separates the base URL from the query parameters. For example: https://example.com/search?query=term In this URL, the question mark "?" indicates the start of the query parameters.
• Identify Key-Value Pairs: Query parameters are made up of key-value pairs, in which a key is linked to a value using the equal symbol ('='). Ampersands ('&') separate multiple key-value pairs. For instance, go to https://example.com/search?query=term&category=books. There are two key-value pairs in this URL: query=term and category=books.
• Recognize Keys and Values: The key is the name or identifier of the parameter, and the value is the data associated with that key. In the example above, "query" is the key, and "term" is the value.
• Handle Special Characters: Be aware that both keys and values in query parameters may need to be URL-encoded if they contain special characters or spaces. URL encoding replaces special characters with percent-encoded representations.
• Additional Query Parameters: If there are multiple query parameters, they are separated by ampersands ('&'). For example: https://example.com/search?query=term&category=books&sort=asc In this URL, there are three query parameters: "query=term," "category=books," and "sort=asc."
• Query Parameter Order: The order of query parameters in the URL generally does not matter, as web servers and applications should be able to interpret them correctly regardless of their order.
• Repeating Query Parameters: Query parameters can be repeated multiple times in a URL, separated by ampersands ('&'). This is useful for cases where you need to pass multiple values for the same parameter. For example, the following URL uses multiple query parameters to filter the results of a search: https://example.com/search?q=cats&category=books&category=movies In this example, the category query parameter is repeated twice, with different values for each repetition. This tells the web server to only return results that are both about cats and are either books or movies.

Query parameters are a powerful tool for passing data to web servers and APIs. By understanding how to document query parameters, you can develop effective and error-free documentation.

Fragment Identifiers in URLs

In our example URL, the fragment identifier is: my-fragments.

Fragment identifiers are a way to identify a specific location within a web page or other resource. They are typically used to link to specific sections of a web page or to provide deep links to specific resources. Fragment identifiers are indicated by a hash sign (#) followed by a unique identifier. For example, the following URL uses a fragment identifier to link to the "Introduction" section of a web page: https://example.com/my-page#Introduction

When a user clicks on a link to a fragment identifier, their browser will scroll to the specified location within the resource.

How to Identify a Fragment Identifier

To identify a fragment identifier in a URL, look for the hash sign (#) followed by a unique identifier. The fragment identifier is everything after the hash sign, but it does not include the hash sign itself. For example, in the following URL, the fragment identifier is "myjob": https://example.com/my-page#myjob

Fragment identifiers are a useful way to make your web pages and API documentation more user-friendly and informative. By understanding how to identify and use fragment identifiers, you can help your users find the information they need quickly and easily.