Backend and HTTP: Who Does What, Methods and Status Codes

In this lesson#

This lesson is built from two chapters, in the same order as the slides:

1. Chapter 1 — what a Backend is: Client, Server, Database, API and Endpoint
2. Chapter 2 — HTTP Methods and Status Codes

Chapter 1: What a Backend Is — Client, Server, Database, API and Endpoint#

What will we learn?#

Now we move from programs that run on our own computer to software that others talk to over the network. This lesson gives the big picture and the words:

• Backend and Frontend.
• Client, Server and Database: how they work together.
• API and Endpoint.

Why do we need this?#

Every app you know (Wolt, Instagram, the bank’s website) is built from two parts: what you see (the Frontend), and what happens “behind the scenes” (the Backend): saving the data, checking permissions, calculating prices. Full Stack developers write both. Data developers work every day with APIs and databases.

By the end of these topics you will build a real Backend: a server that receives requests from the internet, saves to a database, and returns responses.

Explanation from the basics#

Frontend versus Backend#

Client, Server, Database — the three players#

Remember the topic on the computer, the operating system and the network? The Client initiates, the Server answers. Now we add a third player:

  ┌──────────┐   HTTP Request    ┌──────────┐     SQL query     ┌──────────┐
  │  Client  │ ────────────────► │  Server  │ ─────────────────► │ Database │
  │ (browser,│                   │ (FastAPI │                    │ (MySQL)  │
  │  app)    │ ◄──────────────── │  backend)│ ◄───────────────── │          │
  └──────────┘   HTTP Response   └──────────┘     rows           └──────────┘

1. The Client sends a Request: “give me the list of students”.
2. The Server (our Backend) receives it, understands what is being asked, and checks permissions and rules.
3. The server asks the Database: “SELECT all the students”. (This is another Client-Server: towards the Database, our server is the Client! We saw this in the networking practice.)
4. The Database returns rows.
5. The server processes them and returns a Response to the Client, usually as JSON (remember the JSON lesson!).

Why doesn’t the Client talk directly to the Database? Because then every user could read and delete everything. The Server is the guard: it decides what is allowed, checks validity, and enforces rules. Exactly like Encapsulation in the OOP topic, only at the level of the whole system.

API — Application Programming Interface#

API = an interface that a piece of software exposes, so that other software can use it. An interface = a defined set of actions: what you can ask for, how you ask, and what you get back.

You already know the idea! In OOP, the Public Interface of a Class (the public methods) is exactly “an object’s API”. A Web API is the same idea over the network: instead of shop.place_order(...), you send an HTTP request.

Endpoint#

Endpoint = one address in the API + one action. The combination of a Method (GET/POST…) and a Path (/students).

GET     /students        → list all students
GET     /students/7      → get student 7
POST    /students        → create a new student
PUT     /students/7      → update student 7
DELETE  /students/7      → delete student 7

These are five different Endpoints, even though some of them share the same Path. The Method is part of the “address”.

Resource = the “thing” the API manages: students, products, orders. An accepted convention: the Path in the plural, and an identifier after a slash.

What does the Backend do on every request?#

What an API response looks like#

When the Client turns to an API, it sends a request, and the server returns a response. This is what both look like — for example, a request to GitHub’s API about a user named octocat:

GET /users/octocat              <- the request
Host: api.github.com

HTTP/1.1 200 OK                 <- the response
Content-Type: application/json

{"login": "octocat", "name": "The Octocat", "public_repos": 8}

An API returns data and not a display: every Client — a website, a phone app or another program — gets the same data and displays it in its own way.

Later on we will learn to build an API like this ourselves, with FastAPI.

Common mistake#

Mistake 1: “The Frontend will save the data, why do we need a Backend?” Data in the browser stays with one user, on one computer, and anyone can change it. A price saved in the browser? A user can change it to 1 NIS. Everything that needs to be reliable, shared and secure lives in the Backend.

Mistake 2: confusing an API with a Database. The API is the door. The Database is the storeroom behind it. The Client never gets direct access to the storeroom, and always goes through the door, with its rules.

Mistake 3: Paths that describe actions instead of resources.

GET  /getAllStudents
POST /createNewStudent
GET  /deleteStudent?id=7

The convention (called REST): the Path is a noun (the resource), and the Method is the verb. DELETE /students/7 and not GET /deleteStudent. In particular: GET never changes data. Browsers and search-engine robots send GET automatically, and deleting through GET is a recipe for disaster. (We will expand on this in the second chapter.)

Summary#

• Frontend = what the user sees. Backend = logic, data and security, on the server.
• The flow: Client → Server → Database → Server → Client. The server is the guard: the Client does not access the Database directly.
• API = an interface that software exposes to other software. On the Web, through HTTP and JSON.
• Endpoint = Method + Path. GET /students/7 and DELETE /students/7 are two different Endpoints.
• The convention: Path = a resource (a noun, in the plural). Method = an action. GET does not change data.

Official documentation#

• MDN — Introduction to the server side
• MDN Glossary — API
• MDN Glossary — JSON

Chapter 2: HTTP Methods and Status Codes#

What will we learn?#

• The four main HTTP Methods: GET, POST, PUT, DELETE.
• How they map to CRUD: Create, Read, Update, Delete.
• Basic Status Codes: which code to return when.
• What a request and a response look like in each of the actions.

Why do we need this?#

In the students API topic you will write a server, and for every Endpoint you will need to decide: which Method? Which code to return on success, and which on every kind of failure? A Client that talks to your server (an app, a Frontend, another service) decides what to do according to the code: show the data, show “not found”, or ask the user to fix a form. A wrong code = a Client that behaves incorrectly.

Explanation from the basics#

CRUD — the four actions on data#

Almost every system does four things with its data:

This table is the whole backend part. Every row will be an Endpoint, and a function that runs SQL.

The four Methods#

GET — reading.

• “Give me”: GET /students, GET /students/7.
• No Body. All the information is in the Path and the Query (in the next lesson).
• Changes nothing on the server. It is called Safe. You can send it 100 times, and nothing will change.

POST — creating.

• “Create something new”: POST /students, with a Body that describes it.
• Every send creates another item. Two sends = two students.
• Usually the server sets the identifier (id) and returns the new item.

PUT — updating (replacing).

• “Update this item”: PUT /students/7, with a Body of all the new data.
• Sending the same request again = the same result (the student stays with the same values). It is called Idempotent.

DELETE — deleting.

• “Delete this item”: DELETE /students/7.
• Usually no Body.

(There are more Methods, like PATCH for a partial update of single fields, but these four are enough for us.)

Status Codes — what the server answers#

A reminder from the topic on the computer, the operating system and the network: 2xx success, 4xx the Client’s mistake, 5xx the server’s mistake. These are the codes we will use:

The decision principle:

Did it work?
├── yes → created something new?  → 201
│         nothing to return?      → 204
│         otherwise               → 200
└── no  → the client's fault?
          ├── resource doesn't exist        → 404
          ├── wrong structure / types       → 422
          ├── breaks a business rule        → 400
          ├── conflicts with existing data  → 409
          └── our code crashed              → 500  (fix the bug!)

4xx versus 5xx — why does it matter?#

• 4xx = “you (the Client) need to change something”: fix the form, or ask for something that exists. Trying again without a change will fail again.
• 5xx = “I (the server) failed”. The Client did nothing wrong. The server’s code needs fixing.

A server that returns 500 on bad user input contains a bug: it should have checked the input and returned a 4xx. (Remember the calculator server from the topic on the computer, the operating system and the network, which crashed on “hello”?)

Requests and responses — examples#

This is what the requests for each of the actions look like, and the code the server returns:

POST   /students     {"name": "Dana"}   -> 201 Created
GET    /students/7                      -> 200 OK
PUT    /students/7   {"name": "Dana C"} -> 200 OK
DELETE /students/7                      -> 204 No Content
GET    /students/99                     -> 404 Not Found

When to send a Body#

Later on, in FastAPI, we will see how our server receives each of these requests and returns the right code.

Common mistake#

Mistake 1: a GET that changes data.

GET /students/7/delete

Browsers preload links, and search engines go over every link (Crawling). A link like this will delete students without anyone meaning to. Changing data: only POST, PUT and DELETE.

Mistake 2: returning 200 for everything, with “error” inside the JSON.

{"status": "error", "message": "student not found"}

…with code 200. The Client (and also browsers and monitoring systems) see 200 and “think” that everything succeeded. The code is part of the response. A student that does not exist = 404.

Mistake 3: 500 on bad input. A server that runs int(age) without checking, and crashes on "abc" → 500. This is not a mistake of the Client, which should not be punished. It is a bug in the server. Check the input, and return a 4xx with an explanation.

Mistake 4: 404 versus 400. GET /students/999 (valid, but does not exist) → 404. POST /students with age -5 (exists, but not valid) → 400. The question: “does the resource not exist, or is the request not valid?”

Summary#

• CRUD ↔ HTTP: Create = POST, Read = GET, Update = PUT, Delete = DELETE.
• GET is safe: it does not change data, and has no Body. POST/PUT send a Body in JSON with Content-Type: application/json.
• Success: 200 (there is a response), 201 (created), 204 (no content).
• A Client mistake: 404 (does not exist), 400 (breaks a rule), 409 (a conflict), 422 (wrong structure or type).
• 500 = a bug in the server. Bad input should get a 4xx, and not cause a crash.
• The code is part of the response. Don’t return 200 with “error” inside.

Official documentation#

• MDN — HTTP request methods
• MDN — HTTP response status codes
• MDN — HTTP messages

Practice#

Comprehension questions on the lesson material — no code.

Exercise 1: Who does what?#

For each action — does it happen in the Client, in the Server or in the Database?

1. The user clicks the “Sign up” button.
2. Checking that the email is not registered yet.
3. Saving the new student for the long term.
4. Showing the message “You signed up successfully”.
5. Deciding which Status Code to return.

Client  --HTTP request-->  Server  --SQL query-->  Database
Client  <--HTTP response-- Server  <---rows------  Database

Exercise 2: Endpoints#

Write the five Endpoints of an API for managing products (/products): a list, one product, creating, updating and deleting. For each — the Method, the path and what it does.

GET     /products      -> list all products
GET     /products/7    -> get product 7
POST    /products      -> create a new product
PUT     /products/7    -> update product 7
DELETE  /products/7    -> delete product 7

Exercise 3: Reading an API response#

A server returned the following response:

HTTP/1.1 200 OK
Content-Type: application/json

{"login": "octocat", "name": "The Octocat", "public_repos": 8, "blog": null}

1. Did the request succeed? How do you know?
2. In which format is the data, and how do you know?
3. What is the user’s name, and how many repositories do they have?
4. What does null mean?

Exercise 4: CRUD ↔ Methods#

Match each CRUD action to an HTTP Method, and to the suitable response code when it succeeds.

Create    Read    Update    Delete

Exercise 5: Which code to return?#

For each case — which Status Code should the server return?

1. A new student was created.
2. Student 99 was requested, and it does not exist.
3. Someone tried to create a student with an email that is already registered.
4. A student was deleted — and there is nothing to return.
5. Age 7 was sent, but the minimum age is 16.
6. The server crashed because of a bug in the code.