Dynamic and Static: An Overview of HTTP Methods and Resource Operations

Word count: 2177, reading time approximately 11 minutes

In the world of the internet, data flows like blood, driving various applications and services. The RESTful API is the unsung hero behind the scenes, defining a standard “language” that allows different systems to communicate data smoothly.This article serves as the sixth overview guide in the series “Smart API Era: A Practical Guide to RESTful Practices in the AI Age,” introducing you to the most fundamental and important part of this “language”—the HTTP methods. In the following articles, we will delve deeper into each HTTP method.

HTTP Methods: The “Action Guide” for Resources

In the RESTful architecture, each resource has a unique identifier (commonly known as a URL). So, what can we do with these resources? The answer lies in the HTTP methods. You can think of them as the “action guides” for operating resources, as they empower us to communicate with the server.

Let’s get acquainted with these important “action guides”:

GET: The “Explorer” of Information

• Semantics: Used to retrieve information about a specified resource from the server. Like an explorer checking the status of a treasure (resource), it does not modify the treasure itself.
• Idempotency: Executing the same GET request multiple times should yield the same result and have no side effects on the server (i.e., the server does not change anything as a result).
• Safety: Safe and repeatable, as GET requests should not modify any resources on the server.
• Use Cases: Retrieving user information, querying product lists, reading article content, etc.

POST: The “Creator” of Resources

• Semantics: Used to submit new data to the server, requesting the creation of a new resource. Each time you click the submit button, the server may create a new record, just like ordering a new dish at a restaurant.
• Idempotency: Executing the same POST request multiple times may create multiple identical resources on the server, so it is generally not repeatable.
• Safety: Not always safe and does not guarantee repeatability, as POST requests leave resources on the server.
• Use Cases: User registration, order submission, file uploads, posting comments, etc.

PUT: The “Replacer” of Resources

• Semantics: Used to update all information of a specified resource on the server, completely replacing the old content with the new content you provide.
• Idempotency: Executing the same PUT request multiple times should result in a consistent state of the resource. If the first request successfully updates the resource to a certain state, subsequent identical requests will not produce additional side effects.
• Safety: Not always safe but usually repeatable, as PUT requests modify resources on the server.
• Use Cases: Updating user profiles, modifying product information, replacing file content, etc. Typically requires providing a complete representation of the resource.

PATCH: The “Modifier” of Details

• Semantics: Used to update partial information of a specified resource on the server, only needing to inform the server of the changes you want to make. If you only modify a nickname, even if you click the modify button multiple times, the final nickname will be the last one you entered.
• Idempotency: Whether PATCH requests are idempotent depends on the specific implementation. If each request only operates on specific attributes of the resource and the operation is based on the current state of the resource, it may not be idempotent.
• Safety: Not always safe and does not guarantee repeatability, as PATCH requests modify resources on the server.
• Use Cases: Modifying user nicknames, updating order statuses, adjusting article tags, etc. Typically only requires providing the fields that need to be modified.

DELETE: The “Terminator” of Life

• Semantics: Used to request the server to delete a specified resource. The first click of the delete button makes the record disappear. No matter how many times you click delete afterward, the result remains the same.
• Idempotency: Executing the same DELETE request multiple times should result in the resource being deleted. Even if the first request successfully deletes the resource, subsequent identical requests will not produce errors (they may return 404 Not Found), and the server state remains consistent.
• Safety: Not always safe but usually repeatable, as DELETE requests modify resources on the server.
• Use Cases: Deleting user accounts, canceling orders, removing files, etc.

Mapping API Operations to HTTP Methods

Having understood the semantics of HTTP methods, we now need to learn how to map actual API operations to these methods. This is like assigning different tasks to the appropriate “verbs,” making the API design clear and easy to understand.

API Operation	HTTP Method	Description
Retrieve a single resource	GET	Retrieve the resource with the specified ID from the server
Retrieve a list of resources	GET	Retrieve a list of resources from the server that meet certain conditions
Create a new resource	POST	Submit data to the server to create a new resource
Completely update an existing resource	PUT	Replace the resource with the specified ID on the server using the complete data in the request body
Partially update an existing resource	PATCH	Update the resource with the specified ID on the server using partial data in the request body
Delete a specified resource	DELETE	Request the server to delete the resource with the specified ID

Case Studies: Real-World Applications

Let’s look at a few specific cases to see how these HTTP methods play a role in actual API design:

Case Study 1: OpenAI Chat Generation API

• Scenario Description: Request to generate a new conversation
• HTTP Method: POST, as this is an operation to create a new resource (a new conversation), we need to send the context information of the conversation to the server.
• Request URL: /v1/chat/completions

• Request Body (Example):

{
  "model": "gpt-3.5-turbo",
  "messages": [{"role": "user", "content": "Hello!"}]
}

• Response: The server will return JSON data containing the generated conversation content.

Case Study 2: Microsoft Graph API Update User Information

• Scenario Description: Update the user’s display name
• HTTP Method: PATCH, as we only need to update part of the user’s information (the display name), not replace all user information.
• Request URL: /v1.0/users/{user-id} (where {user-id} is the unique identifier for the user)
• Request Body (Example):
```
{
  "displayName": "New Display Name"
}
```
• Response: The server typically returns the updated user information or a success status code.

Case Study 3: Google Drive API Retrieve File List

• Scenario Description: Retrieve the user’s file list
• HTTP Method: GET, as we just want to retrieve file information without modifying the files themselves.
• Request URL (Example): /drive/v3/files
• Response: The server will return JSON data containing the file list.

The “HTTP Methods” and the “Life and Death” of Resources

Let’s elevate our understanding to a philosophical level, “Sorry, I’m showing off again.” As mentioned at the beginning of the article, HTTP methods are the “verbs” of RESTful APIs, empowering us to operate on resources. The “life and death” of resources—creation, updating, and deletion—are driven by these “verbs”.

• POST is the “Birth” of Resources, bringing new data to the server and giving it meaning.
• PUT and PATCH are the “Growth” and “Change” of Resources, allowing us to modify the state of resources as needed, making them more complete.
• DELETE is the “Demise” of Resources, removing unnecessary resources from the system, completing their lifecycle.
• GET is the “Observation” and Retrieval of Resource “Status”, allowing us to understand the current state of resources without intervening in their “life and death”.

It is the flexible use of these “verbs” that enables RESTful APIs to manage and operate various resources clearly and efficiently.

Conclusion

Through this article, you should now have a comprehensive understanding of the crucial HTTP methods in RESTful APIs. Remember, HTTP methods are the “action instructions” for operating RESTful resources, defining what we can do with resources. Mastering the semantics and use cases of GET, POST, PUT, PATCH, and DELETE will make you more adept in API design and development.

This is just the tip of the iceberg in the world of RESTful APIs; we will further explore resource design, the use of status codes, and how to build more robust and maintainable APIs. Stay tuned!