Activity 29: HTTP Methods

Understanding HTTP Methods in RESTful APIs

RESTful APIs, which follow the Representational State Transfer architectural style, rely on HTTP methods to define the actions performed on resources. These methods, also known as CRUD operations (Create, Read, Update, Delete), provide a standardized way for clients to interact with servers. This document will explore the five most common HTTP methods: GET, POST, PUT, DELETE, and PATCH, highlighting their functionalities, use cases, and differences.

1. GET: Retrieving Data from the Server

The GET method is used to retrieve data from a server. It is a read-only operation, meaning it doesn't modify the server's state. GET requests are typically used to fetch resources, such as data, files, or web pages.

When to Use GET:

• Retrieving data: Fetching information about a specific resource or a collection of resources.

• Caching: GET requests are often cached by browsers and proxies, improving performance.

• Bookmarking: GET requests can be bookmarked and shared as they don't have side effects.

Examples:

• /users: Retrieve a list of all users.

• /users/123: Retrieve the details of a user with ID 123.

• /products/search?query=shoes: Search for products related to "shoes".

Code Example (Node.js with Express):

app.get('/users', (req, res) => {
  const users = getUsers(); // Function to fetch users from a database or data source
  res.json(users);
});

2. POST: Creating New Resources

The POST method is used to send data to a server to create a new resource. This method is not idempotent, meaning multiple identical POST requests will result in the creation of multiple resources.

When to Use POST:

• Creating new resources: Adding a new user, creating a new post, or uploading a file.

• Sending data: Submitting forms, posting comments, or sending messages.

• Complex actions: Performing actions that require multiple steps, such as processing a payment.

Examples:

• /users: Create a new user account.

• /posts: Create a new blog post.

• /orders: Place a new order.

Code Example (Node.js with Express):

app.post('/users', (req, res) => {
  const newUser = req.body; // Extract user data from the request body
  const createdUser = createUser(newUser); // Function to create a new user in the database
  res.status(201).json(createdUser);
});

3. PUT: Updating Existing Resources

The PUT method is used to update an existing resource on the server. It replaces the entire resource with the data provided in the request body. PUT requests are idempotent, meaning multiple identical PUT requests will have the same effect as a single request.

When to Use PUT:

• Replacing existing resources: Updating a user's profile, modifying a product's details, or changing a file's content.

• Complete resource updates: When the entire resource needs to be replaced with new data.

Examples:

• /users/123: Update the profile of the user with ID 123.

• /products/456: Replace the details of the product with ID 456.

• /files/document.pdf: Upload a new version of the "document.pdf" file.

Code Example (Node.js with Express):

app.put('/users/:id', (req, res) => {
  const userId = req.params.id;
  const updatedUser = req.body; 
  const updated = updateUser(userId, updatedUser); // Function to update the user in the database
  res.status(200).json(updated);
});

4. DELETE: Removing Resources

The DELETE method is used to remove a resource from the server. DELETE requests are idempotent, meaning multiple identical DELETE requests will have the same effect as a single request.

When to Use DELETE:

• Deleting resources: Removing a user account, deleting a post, or removing a file.

• Removing data: Clearing a shopping cart, deleting a message, or removing a comment.

Examples:

• /users/123: Delete the user with ID 123.

• /posts/456: Delete the post with ID 456.

• /files/document.pdf: Delete the "document.pdf" file.

Code Example (Node.js with Express):

app.delete('/users/:id', (req, res) => {
  const userId = req.params.id;
  const deleted = deleteUser(userId); // Function to delete the user from the database
  res.status(204).send(); // Send a 204 No Content response
});

5. PATCH: Partial Updates to Resources

The PATCH method is used to apply partial updates to an existing resource. It modifies only the specified fields of the resource, leaving the rest unchanged. PATCH requests are not idempotent, meaning multiple identical PATCH requests may lead to different results.

When to Use PATCH:

• Updating specific fields: Changing a user's email address, updating a product's price, or modifying a file's metadata.

• Partial resource updates: When only specific parts of a resource need to be modified.

Examples:

• /users/123: Update the email address of the user with ID 123.

• /products/456: Change the price of the product with ID 456.

• /files/document.pdf: Update the "document.pdf" file's title.

Code Example (Node.js with Express):

app.patch('/users/:id', (req, res) => {
  const userId = req.params.id;
  const updatedFields = req.body; 
  const updated = patchUser(userId, updatedFields); // Function to partially update the user in the database
  res.status(200).json(updated);
});

Key Differences between PUT and PATCH:

• Idempotency: PUT requests are idempotent, while PATCH requests are not.

• Scope of Update: PUT replaces the entire resource, while PATCH modifies only the specified fields.

Choosing the Right Method:

• Use GET for retrieving data.

• Use POST for creating new resources.

• Use PUT for replacing existing resources entirely.

• Use DELETE for removing resources.

• Use PATCH for applying partial updates to resources.