HTTP Guide

HTTP

Hypertext Transfer Protocol (HTTP) is an application-layer protocol for transmitting hypermedia documents, such as HTML. It was designed for communication between web browsers and web servers, but it can also be used for other purposes. HTTP follows a classical client-server model, with a client opening a connection to make a request, then waiting until it receives a response. HTTP is a stateless protocol, meaning that the server does not keep any data (state) between two requests. - MDN Web Docs

HTTP Request Methods

HTTP methods define the actions that can be performed on resources identified by URLs. Here’s a summary of the commonly used methods:

• GET:

  • Purpose: Retrieves data from the server.
  • Usage: Used to request data from a specified resource without modifying it. The data is sent as part of the URL, typically in the query string.
  • Example: GET /api/users fetches a list of users.

• POST:

  • Purpose: Submits data to be processed by the server.
  • Usage: Used to create a new resource or submit data for processing. The data is included in the body of the request.
  • Example: POST /api/users with a request body containing user details creates a new user.

• PUT:

  • Purpose: Updates or replaces an existing resource.
  • Usage: Used to send data to the server to update an existing resource or create a resource if it does not already exist. The data is included in the body of the request.
  • Example: PUT /api/users/123 with a request body containing updated user details replaces the user with ID 123.

• DELETE:

  • Purpose: Deletes a specified resource.
  • Usage: Used to request the removal of a resource identified by a URL.
  • Example: DELETE /api/users/123 deletes the user with ID 123.

• PATCH:

  • Purpose: Partially updates a resource.
  • Usage: Used to apply partial modifications to a resource. The changes are included in the body of the request.
  • Example: PATCH /api/users/123 with a request body containing partial user data updates specific fields of the user with ID 123.

HTTP Request Structure

An HTTP request is composed of several key components that convey information from the client to the server. Here’s an overview of its structure:

• Request Line:
  • Method: Specifies the action to be performed (e.g., GET, POST, PUT, DELETE, PATCH).
  • URL: Indicates the resource being requested or the endpoint. It may include a path and query parameters.
  • HTTP Version: Specifies the HTTP protocol version being used (e.g., HTTP/1.1).

Example:

GET /api/users?age=25 HTTP/1.1

• Headers:
  • Purpose: Provide additional information about the request, such as content type, user agent, and authentication details.
  • Common Headers:
  • Content-Type: Specifies the media type of the request body (e.g., application/json).
  • Authorization: Contains credentials for authenticating the request (e.g., Bearer token).
  • Accept: Indicates the media types that the client is willing to receive (e.g., application/json).

Example:

  Content-Type: application/json
  Authorization: Bearer <token>
  Accept: application/json

• Body:
  • Purpose: Contains data sent with the request, typically used with methods like POST, PUT, and PATCH. Note that the body is not used with GET requests.
  • Content: Can include various data formats, such as JSON, XML, or form-encoded data, depending on the Content-Type header.

Example:

  {
    "name": "John Doe",
    "age": 30
  }

Example HTTP Request:

POST /api/users HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Accept: application/json

{
  "name": "John Doe",
  "age": 30
}

HTTP Response Structure

An HTTP response consists of several key components that provide information from the server to the client. Here’s an overview of its structure:

• Status Line:
  • HTTP Version: Specifies the HTTP protocol version being used (e.g., HTTP/1.1).
  • Status Code: Indicates the result of the request (e.g., 200, 404, 500).
  • Reason Phrase: Provides a textual description of the status code (e.g., OK, Not Found).

Example:

HTTP/1.1 200 OK

• Headers:
  • Purpose: Provide additional information about the response, such as content type, server details, and caching directives.
  • Common Headers:
  • Content-Type: Specifies the media type of the response body (e.g., application/json).
  • Content-Length: Indicates the size of the response body in bytes.
  • Cache-Control: Directs how the response should be cached by browsers or intermediate proxies.

Example:

  Content-Type: application/json
  Content-Length: 123
  Cache-Control: no-cache

• Body:
  • Purpose: Contains the data returned by the server in response to the client's request. This can be in various formats such as JSON, HTML, or plain text.
  • Content: The format and structure of the body depend on the Content-Type header and the specific resource being returned.

Example:

  {
    "id": 123,
    "name": "John Doe",
    "age": 30
  }

Example HTTP Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 123
Cache-Control: no-cache

{
  "id": 123,
  "name": "John Doe",
  "age": 30
}

HTTP Headers

HTTP headers are key-value pairs sent in both HTTP requests and responses. They provide essential metadata and instructions for both clients and servers. Headers are used to convey information about the request or response, control the behavior of the web communication, and manage various aspects of the interaction.

Important HTTP Headers

Here's an overview of some crucial HTTP headers, including their purposes and examples of values they can take:

• Authorization:

  • Purpose: Contains credentials for authenticating the request. It is used to provide access tokens or other authentication data.
  • Examples:
  • Authorization: Bearer <token>
  • Authorization: Basic dXNlcjpwYXNzd29yZA==

• Accept:

  • Purpose: Specifies the media types that the client is willing to receive from the server. It helps the server understand what formats the client can handle.
  • Examples:
  • Accept: application/json
  • Accept: text/html, application/xhtml+xml
  • Accept: */*

• Cookie:

  • Purpose: Sends stored cookies from the client to the server. It is used to maintain session state and track user information.
  • Examples:
  • Cookie: sessionId=abc123; userId=7890
  • Cookie: theme=dark; language=en-US

• Set-Cookie:

  • Purpose: Sends cookies from the server to the client for storage. It allows the server to set cookies that will be sent back by the client in future requests.
  • Examples:
  • Set-Cookie: sessionId=abc123; Path=/; HttpOnly
  • Set-Cookie: userId=7890; Expires=Wed, 21 Aug 2024 07:28:00 GMT; Secure

• Content-Length:

  • Purpose: Indicates the size of the response body in bytes. It allows the client to determine when the response has been fully received.
  • Examples:
  • Content-Length: 1234
  • Content-Length: 0 (for responses with no body)

• Content-Type:

  • Purpose: Specifies the media type of the response body. This informs the client about the type of data being sent.
  • Examples:
  • Content-Type: application/json
  • Content-Type: text/html; charset=utf-8
  • Content-Type: image/png

• Location:

  • Purpose: Used in redirections to specify the URL to which the client should be redirected. This header is typically used with status codes like 3xx.
  • Examples:
  • Location: /new-page
  • Location: https://example.com/login

• Host:

  • Purpose: Specifies the domain name of the server and, optionally, the port number. It is used to direct the request to the correct server in cases of virtual hosting.
  • Examples:
  • Host: example.com
  • Host: api.example.com:8080

• Content-Disposition:

  • Purpose: Specifies how the content should be displayed or handled by the client, typically used for file downloads.
  • Examples:
  • Content-Disposition: attachment; filename="example.pdf"
  • Content-Disposition: inline; filename="document.html"

HTTP Status Codes

HTTP status codes are three-digit numbers returned by the server in response to an HTTP request. They indicate the result of the request and provide information about the response's success, failure, or other outcomes. Here’s an overview of the most important and commonly used HTTP status codes:

1xx Informational

• 100 Continue:
  • Purpose: Indicates that the initial part of a request has been received and the client should continue with the request.
  • Example: Typically used in situations where the client needs to wait for further instructions.

2xx Success

• 200 OK:

  • Purpose: Indicates that the request was successful, and the server has returned the requested data.
  • Examples:
  • 200 OK for a successful GET request with data returned.
  • 200 OK for a successful POST request indicating that the resource was created.

• 201 Created:

  • Purpose: Indicates that the request was successful and a new resource has been created.
  • Examples:
  • 201 Created for a successful POST request creating a new user.
  • 201 Created when a new resource is successfully added to a database.

• 204 No Content:

  • Purpose: Indicates that the request was successful, but there is no content to send in the response body.
  • Examples:
  • 204 No Content for a successful DELETE request.
  • 204 No Content for a successful PUT request where no additional data needs to be returned.

3xx Redirection

• 301 Moved Permanently:

  • Purpose: Indicates that the resource has been permanently moved to a new URL, and future requests should use this URL.
  • Examples:
  • 301 Moved Permanently when a website URL has changed permanently.
  • 301 Moved Permanently used in SEO for redirecting old URLs to new ones.

• 302 Found:

  • Purpose: Indicates that the resource has been temporarily moved to a new URL, but future requests should continue to use the original URL.
  • Examples:
  • 302 Found for temporary redirections, such as during login flows.
  • 302 Found when a resource is temporarily available at a different location.

• 304 Not Modified:

  • Purpose: Indicates that the resource has not been modified since the last request, so the client can use its cached version.
  • Examples:
  • 304 Not Modified when caching headers are used to check if content has changed.
  • 304 Not Modified in response to conditional GET requests to improve performance.

4xx Client Error

• 400 Bad Request:

  • Purpose: Indicates that the server could not understand the request due to invalid syntax.
  • Examples:
  • 400 Bad Request for malformed request syntax or invalid request message framing.
  • 400 Bad Request when missing required fields in a POST request.

• 401 Unauthorized:

  • Purpose: Indicates that authentication is required and has failed or has not yet been provided.
  • Examples:
  • 401 Unauthorized for missing or invalid authentication credentials.
  • 401 Unauthorized when accessing protected resources without valid credentials.

• 403 Forbidden:

  • Purpose: Indicates that the server understands the request but refuses to authorize it.
  • Examples:
  • 403 Forbidden for requests where the client does not have permission to access the resource.
  • 403 Forbidden when the server refuses to fulfill the request for security reasons.

• 404 Not Found:

  • Purpose: Indicates that the server could not find the requested resource.
  • Examples:
  • 404 Not Found when accessing a non-existent URL.
  • 404 Not Found for resources that have been moved or deleted.

5xx Server Error

• 500 Internal Server Error:

  • Purpose: Indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  • Examples:
  • 500 Internal Server Error due to server-side code errors.
  • 500 Internal Server Error when there is a problem with the server configuration.

• 502 Bad Gateway:

  • Purpose: Indicates that the server received an invalid response from an upstream server it accessed in attempting to fulfill the request.
  • Examples:
  • 502 Bad Gateway when a reverse proxy or gateway server receives an invalid response.
  • 502 Bad Gateway during network issues between servers.

• 503 Service Unavailable:

  • Purpose: Indicates that the server is currently unable to handle the request due to temporary overloading or maintenance.
  • Examples:
  • 503 Service Unavailable during server maintenance.
  • 503 Service Unavailable when the server is temporarily overloaded.

HTTP Request Examples

Here are various examples of HTTP requests, demonstrating different methods and use cases:

• GET Request:

  GET /api/users?age=25 HTTP/1.1
  Host: example.com
  Accept: application/json

• POST Request:

  POST /api/users HTTP/1.1
  Host: example.com
  Content-Type: application/json
  Authorization: Bearer <token>

  {
    "name": "John Doe",
    "age": 30
  }

• PUT Request:

  PUT /api/users/123 HTTP/1.1
  Host: example.com
  Content-Type: application/json
  Authorization: Bearer <token>

  {
    "name": "John Doe",
    "age": 31
  }

• DELETE Request:

  DELETE /api/users/123 HTTP/1.1
  Host: example.com
  Authorization: Bearer <token>

• PATCH Request:

  PATCH /api/users/123 HTTP/1.1
  Host: example.com
  Content-Type: application/json
  Authorization: Bearer <token>

  {
    "age": 32
  }

HTTP Response Examples

Here are various examples of HTTP responses, demonstrating different status codes, headers, and scenarios, including setting cookies and file downloads:

• 200 OK Response with Set-Cookie:

  HTTP/1.1 200 OK
  Content-Type: application/json
  Content-Length: 123
  Set-Cookie: sessionId=abc123; Path=/; HttpOnly
  Date: Wed, 14 Aug 2024 12:00:00 GMT

  {
    "message": "Request was successful",
    "data": {
      "userId": 1,
      "userName": "John Doe"
    }
  }

• 201 Created Response with Location Header:

  HTTP/1.1 201 Created
  Content-Type: application/json
  Location: /api/users/123
  Content-Length: 45
  Date: Wed, 14 Aug 2024 12:05:00 GMT

  {
    "message": "User created successfully",
    "userId": 123
  }

• 204 No Content Response:

  HTTP/1.1 204 No Content
  Date: Wed, 14 Aug 2024 12:10:00 GMT

• 400 Bad Request Response:

  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  Content-Length: 55
  Date: Wed, 14 Aug 2024 12:15:00 GMT

  {
    "error": "Invalid request",
    "message": "The request body is missing required fields"
  }

• 404 Not Found Response:

  HTTP/1.1 404 Not Found
  Content-Type: text/html
  Content-Length: 150
  Date: Wed, 14 Aug 2024 12:20:00 GMT

  <!DOCTYPE html>
  <html>
  <head><title>404 Not Found</title></head>
  <body>
    <h1>404 Not Found</h1>
    <p>The requested resource was not found on this server.</p>
  </body>
  </html>

• 200 OK Response with File Download (Content-Disposition):

  HTTP/1.1 200 OK
  Content-Type: application/pdf
  Content-Disposition: attachment; filename="report.pdf"
  Content-Length: 102400
  Date: Wed, 14 Aug 2024 12:30:00 GMT

  %PDF-1.4
  % binary content of the PDF file...