In the previous chapter, you learned about the main components of a REST API. I promised to dive deeper into the terms and definitions so that you have a clear understanding of them. So here we go.
Let’s start with an example URL: https://www.google.com/search?q=cats#my-fragment
The above URL has following components, and we document all of them if present:
- Protocol:
https://
- Domain name:
www.google.com
- Path:
/search
- Query parameters:
q=cats
- Fragment identifier:
my-fragments
Let’s see everything in detail. Select the appropriate tabs for more information. For example, if you want all the relevant information on domain name, select the Domain Name tab.
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.
![Top 9 HTTP Request Methods Top 9 HTTP Request Methods](./images/http_methods.jpg)
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.
-
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.
-
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.
-
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.
-
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.
-
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:
-
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
- HTTP protocol:
-
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. -
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.
-
Note Any Secure Connections: If the URL begins with
https://
instead ofhttp://
, 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.
- What is the purpose of the HTTP GET method?
- When is the HTTP POST method typically used?
- How does the HTTP PUT method differ from the PATCH method?
- What HTTP method is used for resource deletion?
- Where can you find the protocol in a URL?
- What is the significance of the protocol keyword in a URL?
- How do HTTP and HTTPS protocols differ in terms of security?
- What does it mean when a URL starts with "https://"?
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:
- User's Request: You type "www.adventureland.com" into your browser.
- DNS Request: Your browser asks the DNS server for the website's IP address.
- DNS Lookup: The DNS server finds the IP address for "www.adventureland.com" (e.g., it's 192.168.1.1).
- Browser's Journey: Your browser sails to the server at IP address 192.168.1.1.
- Server Interaction: Your browser asks the server, "Show me www.adventureland.com."
- Server Response: The server responds with the website's content.
- 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.
- What exactly is a domain name, and how does it relate to a website's internet address?
- Why is the domain name often referred to as the website's URL?
- What is the difference between a top-level domain (TLD) and a second-level domain (SLD)?
- Can you give examples of common TLDs and SLDs?
- When you enter a domain in your browser, what happens behind the scenes to locate the website?
- What is the role of the DNS (Domain Name System) server in the process?
- How does the DNS server find the IP address associated with a domain name?
- Why is the IP address crucial for your browser to connect to the website's server?
- Why are domains important in the context of API documentation?
- How does knowing the domain of an API server help you when using an API?
- Can you identify the domain in a given API URL, and why is it essential to do so?
- What role does the API server's domain play in sending requests and receiving API responses?
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:
- Locate the Domain: The domain is usually the first part of the URL, like "https://www.example.com."
- 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.
- 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.
- Where does the path start? (Hint: After the domain)
- What's in the path? (Think of it as folders in a website)
- What specific resource or content does the path point to?
- How does the path hierarchy relate to the website's structure?
- Do any segments in the path indicate user categories or content types?
- Is there a pattern in the path that conveys information?
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
andcategory=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.
- What are query parameters and what is their purpose in a URL?
- How are query parameters separated from the base URL?
- What symbol is used to introduce query parameters in a URL?
- Explain the structure of a key-value pair in query parameters.
- Why might you need to URL-encode query parameters?
- How are multiple query parameters separated from each other in a URL?
- What is the purpose of a fragment identifier in a URL, and how is it different from query parameters?
- Does the order of query parameters in a URL matter for interpretation?
- When and why would you repeat a query parameter with different values in a URL?
- What is the role of query parameters in passing data to web servers and APIs?
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.
- What is a fragment identifier in a URL, and what is its purpose?
- How is a fragment identifier indicated in a URL?
- What is the significance of the hash sign (#) in a fragment identifier?
- How can fragment identifiers enhance user experience on web pages?
- Is it possible to have both query parameters and a fragment identifier in the same URL?
- How can you identify a fragment identifier within a URL?
Course completed
Have an issue? Please provide specific feedback by reporting an issue.