HTTP (HyperText Transfer Protocol) & HTTPS (HTTP Secure)

HTTP is a protocol that allows data transfer between a client and a server. HTTPS is the secure version of HTTP. It is used in secure communication over the internet. With https, the client’s system encrypts the data before sending it to the server. The server then decrypts the data and processes it. The server also encrypts the response data and sends the encrypted data to the client. The client’s browser then decrypts the data and displays it to the user. The secure content makes it difficult to steal and retrieve information from the server.

HTTP Methods (Aka Verbs)

There are 5 HTTP methods that are commonly used when accessing data over http. They are:

• GET - Used to retrieve data from the server. Returns the requested resource. If not found, returns a 404 Not Found status code. A GET call doesn’t need a payload. However, GET calls can be accompanied by query string parameters and their values to filter the API output.
• POST - Used to send data to the server. Creates a record. The POST request always comes with an HTTP request body containing JSON or Form URL encoded data, which is also called a payload. If the data is valid, the API endpoint will create a new resource based on these data. Although you can create multiple resources with a single POST call, it is not considered a best practice to do so.
• PUT - Used to update data on the server. Instructs the API to replace a resource. Like a POST request, the PUT request also comes with data. A PUT request usually supplies all data for a particular resource so that the API developer can fully replace that resource with the provided data. A PUT request deals with a single resource.
• DELETE - Instructs the API to delete data from the server. When the DELETE request is sent to a collection endpoint, the API should delete the entire collection. When the DELETE request is sent to a single resource endpoint, the API should delete that specific resource.
• PATCH - Used to update a specific part of the data on the server (partial update). Tells the API to update a part of the resource. Note the difference between a PUT and a PATCH call. A PUT call replaces the complete resource, while the PATCH call only updates some parts. A PATCH request also deals with a single record.

HTTP Requests

HTTP requests are sent by the client to the server. So they are different types of information encoded by a browser. A typical HTTP request looks like this:

GET /api/v1/users/ HTTP/1.1

It consists of 5 parts:

• Version type - most used are 1.1 and 2.0
• URL
• HTTP Method
• Request Headers - core part of every request. They generally include Server Name, Server Port, Request method and Content type.They contain extra information for the server to process the request and make decisions on how to present the content. Example: Cookie, User-Agent, Referrer, etc.
• Request Body (optional) - passed as either a raw JSON string or a form URL encoded string.

HTTP Responses

HTTP responses are sent by the server to the client. The browser then processes the response and displays the content to the user. The response contains the requested resource. A typical HTTP response looks like this:

HTTP/1.1 200 OK
Date: Mon, 22 Nov 2022 12:28:53 GMT
Server: Apache/2.2.14 (Win32)
Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT
Content-Length: 88
Content-Type: text/html

It consists of 4 parts:

• Requested resource
• Content Length
• Content Type
• Headers (example: cookies)
• ETags
• Time last modified
• HTTP Status Code

Response Types

These days, the most common response types involved with REST APIs are JSON, XML, plain text, and sometimes YAML. Frameworks like DRF (Django Rest Framework) come with built-in renderer classes that can convert the data into an appropriate format and display it correctly.

There are also third-party renderers available for this job. While making an API call, the client can specify its desired response format with the Accept HTTP header. And that header should be considered to deliver the result in that format using the render classes. Here’s a list of HTTP headers for different response types.

HTTP Status Codes

HTTP status codes are 3 digit codes that are sent by the server to the client. They are basically for browsers to understand the response.

The first digit of the status code indicates the type of status, with 1xx indicating an informational response, 2xx indicating a successful response, 3xx indicating a redirect, 4xx indicating a client error, and 5xx indicating a server error.

Here are some of the most common types of HTTP status codes:

• Informational Response (1xx): (Provisional & Interim) Informational responses are sent by the server to inform the client that the request has been received and is being processed. These codes do not indicate success or failure, but rather provide feedback to the client about the status of the request. Some common informational response codes include:

  • 100 Continue: This code indicates that the server has received the initial part of the request and the client should proceed with sending the remainder of the request.
  • 101 Switching Protocols: This code indicates that the server is changing protocols and the client should switch to the new protocol.
  • 102 Processing: This code indicates that the server has received and is processing the request, but no response is available yet. This way, the client understands that the result isn’t ready and should be checked again.

• Successful Response (2xx): Successful responses are sent by the server when it successfully processes the client’s request. These codes indicate that the request was successfully received, understood, and processed. Some common successful response codes include:

  • 200 OK: This code indicates that the request was successfully processed and the response body contains the requested information. The GET method will return this code if the resource is found/included, POST will return if Successfully transmitted, PUT will return if Successfully updated, and DELETE will return if Successfully deleted.
  • 201 Created: This code indicates that the request was successfully processed and a new resource was created on the server.
  • 204 No Content: This code indicates that the server has successfully processed the request, but there is no content to return in the response body.

• Redirect (3xx): Redirect codes are sent by the server to redirect the client to a different URL. These codes indicate that the requested resource has moved to a new location, or that the client needs to take additional action to complete the request. Some common redirect codes include:

  • 301 Moved Permanently: This code indicates that the requested resource has permanently moved to a new location.
  • 302 Found: This code indicates that the requested resource has temporarily moved to a new location.
  • 303 See Other: This code indicates that the requested resource can be found at a different URI, and the client should retrieve it using a GET request.
  • 304 Not Modified: This code indicates that the client’s cached copy of the resource is up-to-date and does not need to be refreshed.
  • 307 Temporary Redirect: This code indicates that the requested resource has temporarily moved to a different URI, and the client should use the same method to retrieve it.

• Client Error (4xx): Client error codes are sent by the server when it is unable to process the client’s request due to a problem on the client-side. These codes indicate that the request was invalid or could not be completed due to client-side errors. Some common client error codes include:

  • 400 Bad Request: This code indicates that the server was unable to understand the request due to invalid syntax or other client-side errors.
  • 401 Unauthorized: This code indicates that the client must authenticate itself to get the requested response.
  • 403 Forbidden: This code indicates that the client does not have sufficient permissions to access the requested resource.
  • 404 Not Found: This code indicates that the server was unable to locate the requested resource.

• Server Error (5xx): Server error codes are sent by the server when it encounters an error while processing the request. These codes indicate that the server was unable to complete the request due to an error on its part.

  These alarming status codes are usually automatically generated on the server side if something goes wrong in the code, and the API developer doesn’t write code to deal with those errors. For example, a client requests a non-existing resource, and the API developer tries to display that resource without adequately checking if that resource exists in the database. Or if the API developer didn’t validate the incoming data and attempted to create a new resource with invalid or insufficient data. You, as an API developer, should always avoid 5xx errors.

  Some common server error codes include:

  • 500 Internal Server Error: This code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
  • 501 Not Implemented: This code indicates that the server does not support the functionality required to fulfill the request.
  • 502 Bad Gateway: This code indicates that the server received an invalid response from another server while attempting to fulfill the request.
  • 503 Service Unavailable: This code indicates that the server is currently unable to handle the request due to a temporary overload or maintenance.
  • 504 Gateway Timeout: This code indicates that the server did not receive a timely response from another server while attempting to fulfill the request.

Summary:

Sometimes the same status codes can convey different messages in different contexts. For example, a 200 status code for a GET request means the content was found. The same 200 code for a PUT request means that the data transmission and update process was successful. Similarly, for a DELETE request, this 200 status code means that the resource was successfully deleted.

• 100 - 199: Informational
• 200 - 299: Successful
• 300 - 399: Redirection
• 400 - 499: Client Error
• 500 - 599: Server Error

Client Error codes happen due to bad API requests sent by the client, requesting a resource that does not exist on the server, etc.

Server Error codes happen due to error check issues, configuration mismatch, package dependency issues, etc.

• ← Previous Post
• Next Post →