Activity 29: HTTP Methods

RESTful APIs use several HTTP methods to interact with resources. The RESTful design is based upon the principles of Representational State of Resource which is primarily stateless communication where the manipulation of the resources is done through standard HTTP methods. Here are some of the major HTTP methods that can be found in RESTful APIs:

1. GET: Retrieve Data

GET is used to fetch data from the server. It's a read-only operation that doesn't modify any information on the server. A GET request is also idempotent means that having the same request multiple times will produce the same result. It does not have side effects on the resource.

When to Use:

Retrieving a list of resources.

Retrieving a single resource by its identifier.

Examples:

Fetching a list of users:
```
  bashCopy codeGET /users
```
Retrieving a specific user:
```
  bashCopy codeGET /users/123
```

Headers Example:

  vbnetCopy codeGET /users/123 HTTP/1.1
  Host: api.example.com
  Accept: application/json

Characteristics of GET:

Safe: It doesn't modify the data.
Idempotent: Repeated requests yield the same result.
Cacheable: Responses can be cached, improving performance.

2. POST: Create a New Resource

The POST request is generally used to send information to the server to create a new resource. It's used for forms submission or for data transfer, where data can be processed by the server. The POST request, unlike GET, has the ability to modify the server state by performing actions such as creating a new resource.

When to Use:

Creating a new resource (e.g., adding a new user, creating a blog post).
Submitting data that the server processes and may use to trigger further actions.

Example:

Fetching a list of users:
```
  bashCopy codeGET /users
```
Retrieving a specific user:
```
  bashCopy codeGET /users/123
```

Headers Example:

  vbnetCopy codeGET /users/123 HTTP/1.1
  Host: api.example.com
  Accept: application/json

Characteristics of POST:

Not idempotent: Sending the same POST request multiple times may create multiple resources.
Often used when a new resource must be created on the server.
Does not necessarily result in a new resource URI (it may return a location header for the new resource).

3. PUT: Update an Existing Resource

PUT method updates an existing resource or creates a new one if the resource does not exist. It is usually applied when updating the full representation of the resource. The request's body contains all information with which the resource should be updated, and the server replaces the existing resource with new data.

When to Use:

Replacing an entire resource or overwriting it.
Updating resource data when the client has all the information required to replace it completely.

Example:

Updating user information:

  cssCopy codePUT /users/123
  Body: {
    "name": "nothing",
    "email": "nothing@example.com"
  }

Creating (if supported):

  cssCopy codePUT /users/124
  Body: {
    "name": "nothing",
    "email": "nothing@example.com"
  }

Headers Example:

  makefileCopy codePUT /users/123 HTTP/1.1
  Host: api.example.com
  Content-Type: application/json
  Content-Length: <calculated>

  {
    "name": "nothing",
    "email": "nothing@example.com"
  }

Characteristics of PUT:

Idempotent: Repeating the same PUT request will result in the same resource state.
Can replace an entire resource.
Requires the full resource data in the request.

4. DELETE: Remove a Resource

The DELETE method is used to remove a resource from the server. Once a DELETE request is successfully processed, the resource should no longer exist.

When to Use:

Removing a resource from the server, such as deleting a user, a post, or a file.
It can also be used to remove a resource identified by a URI.

Example:

Deleting a user:
```
  bashCopy codeDELETE /users/123
```

Headers Example:

  bashCopy codeDELETE /users/123 HTTP/1.1
  Host: api.example.com

Characteristics of DELETE:

Idempotent: Sending the same DELETE request multiple times has the same effect, meaning the resource will be deleted once and not affect the state if repeated.
Once the resource is deleted, it can no longer be retrieved.

5. PATCH: Apply Partial Updates

The PATCH method is used to apply partial updates to an existing resource. Unlike PUT, which requires the complete resource to be sent, PATCH only requires the fields that need to be updated.

When to Use:

Making partial updates to an existing resource.
Updating one or more attributes of a resource without replacing the entire resource.

Example:

PATCH /users/123 – Updates the user's data (e.g., only the email field) rather than sending all user details.

Characteristics of PATCH:

Not necessarily idempotent (depending on implementation).
Used for partial updates (e.g., modifying a single field in a resource).
More efficient than PUT if only a subset of a resource needs to be changed.

Comparison Between PUT and PATCH:

PUT is used for full resource updates, where you send the complete updated resource to the server.
PATCH is used for partial updates, where only the fields that need to be changed are sent, making it more efficient when updating a few attributes of a resource.

HTTP Method	Idempotent	Purpose	Use Case Example
GET	Yes	Retrieve data from the server	Fetch a list of users or a single user
POST	No	Create a new resource	Submit a form to create a new user
PUT	Yes	Update or replace an existing resource	Replace the entire data of a user
DELETE	Yes	Delete a resource from the server	Delete a user by ID
PATCH	No	Apply partial updates to a resource	Update only the email of a user

Understanding these methods and when to use them ensures a clean, RESTful architecture that follows best practices for resource management.