Tutorial - HTTP and REST APIs for Developers

Introduction

The Internet is based on numerous technologies, of which HTTP (Hypertext Transfer Protocol) is one of the most important. In this tutorial, you’ll learn the basics of HTTP and REST (Representational State Transfer) to get a simple introduction to the topic. Practical examples will help you deepen your understanding. You’ll also learn more about important concepts such as authentication, security aspects, and caching.

1. What is HTTP?

HTTP (Hypertext Transfer Protocol) is the fundamental communication protocol of the Internet. It enables the exchange of information between a web browser (e.g., Google Chrome, Firefox, or Safari) and a web server where websites and other resources are stored. Every time you enter a URL in your browser’s address bar or click on a link, an HTTP request is sent to the server, which then returns the requested webpage or resource.

Without HTTP, surfing the Internet would not be possible, as it acts as a mediator between the user and the server. It ensures that texts, images, videos, and other content are loaded from a server and displayed correctly in the browser.

1.1 HTTP Methods – How Do Browsers and Servers Communicate?

HTTP offers various methods through which a client (e.g., a browser) can communicate with a server. Each of these methods has a specific purpose:

GET – Retrieves data from a server. This is the most common method and is used for loading web pages.
Example: When you visit a news site, your browser sends a GET request to the server to display the articles and images.
POST – Sends data to the server.
Example: When you fill out and submit a contact form, the entered information is sent to the server via a POST request.
PUT – Updates an existing resource on the server.
Example: An app that allows you to change your profile picture would use a PUT request to upload the new image and replace the old one.
DELETE – Deletes a resource on the server.
Example: In a web application for managing tasks, a DELETE request can be used to permanently remove a task.
PATCH – Updates a resource partially.
Example: A social media platform could use PATCH to change only the status text of a post instead of saving the entire post again.
HEAD – Retrieves only the header information of a resource, not the actual content.
Example: Search engines use HEAD requests to check if a webpage exists and when it was last updated, without loading the entire content.
OPTIONS – Indicates which methods are supported on a server.
Example: A developer might make an OPTIONS request to find out if a server accepts the PUT or DELETE method.

1.2 HTTP Status Codes – What Responses Does the Server Give?

Each HTTP request leads to a response from the server, which is described by so-called status codes. These codes indicate whether a request was successful or if a problem occurred.

Successful Responses (2xx):

HTTP Status	Meaning	Example
200 OK	The request was successful and the desired resource is being returned.	A webpage loads without errors.
201 Created	A new resource was successfully created.	When registering on a website, your user account is created in the system.
204 No Content	The request was successful, but there is no content to send back.	When you save a setting but no new page needs to be loaded.

HTTP Status

Meaning

Example

200 OK

The request was successful and the desired resource is being returned.

A webpage loads without errors.

201 Created

A new resource was successfully created.

When registering on a website, your user account is created in the system.

204 No Content

The request was successful, but there is no content to send back.

When you save a setting but no new page needs to be loaded.

Client Errors (4xx):

HTTP Status	Meaning	Example
400 Bad Request	The request was faulty, often due to incorrect syntax or invalid inputs.	Required fields were not filled out when submitting a form.
401 Unauthorized	Access denied due to invalid authentication.	A protected page requires login that hasn’t been provided.
403 Forbidden	Access to the resource is prohibited.	An internal company website is only accessible to employees.
404 Not Found	The requested page or file was not found.	A user clicks on an old link that no longer exists.

HTTP Status

Meaning

Example

400 Bad Request

The request was faulty, often due to incorrect syntax or invalid inputs.

Required fields were not filled out when submitting a form.

401 Unauthorized

Access denied due to invalid authentication.

A protected page requires login that hasn’t been provided.

403 Forbidden

Access to the resource is prohibited.

An internal company website is only accessible to employees.

404 Not Found

The requested page or file was not found.

A user clicks on an old link that no longer exists.

Server Errors (5xx):

HTTP Status	Meaning	Example
500 Internal Server Error	A general error on the server.	A technical problem in the web application prevents the page from loading.
502 Bad Gateway	The server received an invalid response from another server.	When a web server communicates with a backend service and it doesn’t respond.
503 Service Unavailable	The server is temporarily unavailable, often due to maintenance work.	An online shop is not accessible during a major update.

HTTP Status

Meaning

Example

500 Internal Server Error

A general error on the server.

A technical problem in the web application prevents the page from loading.

502 Bad Gateway

The server received an invalid response from another server.

When a web server communicates with a backend service and it doesn’t respond.

503 Service Unavailable

The server is temporarily unavailable, often due to maintenance work.

An online shop is not accessible during a major update.

These status codes are essential for developers and users as they help identify errors and solve problems quickly.

1.3. Important HTTP Headers for Security, Caching, and Authentication

HTTP headers are an essential component of the communication between client (e.g., browser) and server. They contain additional metadata about the request or response and influence the behavior of websites, APIs, and applications.

Without HTTP headers, many modern web applications couldn’t function, as they are required for authentication, caching, and data processing. They are used in every HTTP request and response to tell the server or client how to handle the sent or received data.

Here are some of the most important HTTP headers with illustrative examples.

1. Content-Type – What Data Format is Being Sent or Expected?

The Content-Type header indicates in which format the data is being transmitted. This is crucial for web browsers, APIs, and servers to ensure correct interpretation and processing of the data.

Example for a JSON response:

Content-Type: application/json

Is used when an API returns a response in JSON format, e.g., in communication between a web app and a server.

Example for an HTML page:

Content-Type: text/html

Signals that the server is sending a webpage in HTML format.

Example for an image file:

Content-Type: image/png

Is set when a server delivers a PNG image file, e.g., for a logo or product image.

2. Authorization – Authentication for Protected Areas

The Authorization header is used to gain access to protected resources, e.g., an API or an internal company page. Without valid authentication, the server denies access with status code 401 Unauthorized.

Example for token-based access (common in modern APIs):

Authorization: Bearer <token>

Often used in web apps to authenticate against a server, e.g., for a protected user account page or an API request with OAuth 2.0.

Example for basic authentication (simple username-password combination):

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Here, the username and password are transmitted as a Base64-encoded string. This method is often used in older systems but is less secure than token-based methods.

3. Cache-Control – How Should Content Be Cached?

The Cache-Control header determines how long a resource may be stored in the browser’s cache or a proxy. This improves loading times and reduces server load by not having to download already loaded content again.

Example for a page that should not be cached:

Cache-Control: no-cache, no-store, must-revalidate

Used e.g., for sensitive data, like online banking pages or private dashboards, to ensure that current content is always loaded.

Example for a resource that may be cached for a week:

Cache-Control: max-age=604800

Useful for static content like logos or fonts that rarely change and can be quickly loaded from the cache.

Example for a cached page that needs regular revalidation:

Cache-Control: public, must-revalidate

Used e.g., for news articles or product pages that change occasionally but should load as quickly as possible.

HTTP headers are a crucial foundation for modern data exchange on the Internet. They control not only how content is transmitted but also how securely and efficiently it is processed.

2. What is REST?

REST (Representational State Transfer) is an architectural style for web services based on the Hypertext Transfer Protocol (HTTP). REST was developed to enable simple, scalable, and flexible communication between distributed systems. Due to its intuitive structure, REST is the foundation of many modern web APIs, including the interfaces of social media platforms, e-commerce websites, and cloud services.

2.1. REST Principles

REST follows several essential principles that ensure efficient and standardized communication.

Client-Server Model

REST is based on a clear separation between client and server. The client sends requests, while the server responds with responses. This separation enables better scalability and flexibility. For example, a web browser (client) can communicate with an online shop server via a REST API to retrieve product data or place orders.

Stateless

Each request to the server contains all necessary information for processing. The server does not store any session state between requests, which leads to simpler scalability.

An example: A mobile banking app client sends a REST request to retrieve the account balance:

GET /account/123456 HTTP/1.1
Host: api.bank.com

Since each request is independent, it already contains the complete identification of the customer account (e.g., 123456).

Resource-Based Design

All data and functions in a REST API are considered resources. Each resource has a unique URL that describes its identity. For example, a user in a system can be retrieved via the following URL:

GET /users/1 HTTP/1.1
Host: api.example.com

Here, /users/1 represents the user with ID 1. The API then returns the corresponding user data.

Use of Standardized HTTP Methods

REST uses common HTTP methods for the main CRUD operations (Create, Read, Update, Delete):

Create → POST

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Anna",
  "email": "anna@example.com"
}

This creates a new user named Anna.

Read → GET

GET /users/1 HTTP/1.1
Host: api.example.com

This retrieves the user with ID 1.

Update → PUT or PATCH

PUT /users/1 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Anna",
  "email": "anna@example.com"
}

This updates the user data from Ana to Anna.

Delete → DELETE

DELETE /users/1 HTTP/1.1
Host: api.example.com

This deletes the user with ID 1 from the system.

Representations of Resources

Data in REST can be returned in various formats. JSON (JavaScript Object Notation) and XML (Extensible Markup Language) are commonly used, but HTML can also be an option.

Example JSON:

{
  "id": 1,
  "name": "Max",
  "email": "max@example.com"
}

This format is easy to understand and is preferred by modern web applications.

Example XML:

<user>
  <id>1</id>
  <name>Max</name>
  <email>max@example.com</email>
</user>

XML is often used in older systems or SOAP web services.

Example HTML:

<div>
  <h1>Max</h1>
  <p>Email: max@example.com</p>
</div>

This format is suitable for direct embedding in web pages.

2.2. Example of a REST API

A REST API provides standardized interfaces for accessing resources. These interfaces enable developers to efficiently communicate with an application by using HTTP methods.

Example: Retrieving User Data

A client can retrieve user data with a GET request:

GET https://api.example.com/users/1

The API responds with the stored user data:

{
  "id": 1,
  "name": "Max",
  "email": "max@example.com"
}

This example shows how easy it is to retrieve data from a REST API.

Example: Creating a New User

If a client wants to add a new user, they send a POST request with the corresponding data:

POST https://api.example.com/users
Content-Type: application/json

{
  "name": "Anna",
  "email": "anna@example.com"
}

The API stores the new user and returns a confirmation:

{
  "id": 2,
  "name": "Anna",
  "email": "anna@example.com"
}

Here you can see how easily new data can be created via a REST API. This principle is applied in many areas, for example when registering new users on social media platforms or in online shops.

2.3. Authentication and Security

The security of REST APIs is a central aspect in the development and use of web services. Various authentication mechanisms ensure that only authorized users and systems can access sensitive data. The following explains some of the most common methods:

API Keys

API keys are one of the simplest methods of authentication. The client receives a unique key that must be transmitted with each request. This method is well-suited for simple use cases such as retrieving public data or identifying a user.

Example: A client sends a request with an API key as an authentication token:

GET /data HTTP/1.1
Host: api.example.com
Authorization: ApiKey 123456789abcdef

Basic Authentication

Basic Authentication is a simple method where username and password are transmitted in the request as a Base64-encoded string. This method should only be used in combination with HTTPS to protect the sensitive credentials from attackers.

Example: A request with Basic Authentication might look like this:

GET /protected-resource HTTP/1.1
Host: api.example.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

There are also more advanced authentication mechanisms like OAuth and JWT (JSON Web Token) that provide a more secure and flexible method for authorization.

Summary

In this tutorial, you have learned the basics of HTTP and REST to expand your understanding of these essential technologies.

First, HTTP was explained as the Internet’s communication protocol, including the various HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS) and their meanings. Then, HTTP status codes were described in detail so you can better understand the different server responses. You also learned about important HTTP headers that play a central role in security, caching, and authentication.

In the second section, you learned about REST (Representational State Transfer) as an architectural style for web services based on HTTP. The central REST principles, including the