API Documentation

Welcome to the People API! This documentation is designed to teach you how APIs work from an absolute beginner level.

2. What is an API?

API stands for Application Programming Interface. It is a set of rules that allows one piece of software application to talk to another. Just like a user interface (UI) allows a human to interact with a system (by clicking buttons), an API allows a computer program to interact with a system (by sending code requests).

3. Client & Server

In web development, computers are divided into two main roles:

• Client: The computer/device asking for data. For example, your web browser or a mobile app.
• Server: The computer holding the data. It waits for requests and serves the data back.

4. HTTP (HyperText Transfer Protocol)

HTTP is the language clients and servers use to talk to each other over the internet. When your client wants data, it sends an HTTP Request. When the server answers, it sends an HTTP Response.

5. Request & Response

A typical interaction looks like this:

Client  ------ (HTTP Request) ------>  Server
        <------ (HTTP Response) -----

6. Endpoints

An endpoint is a specific URL where an API can be accessed. Think of it like a specific department in a large building. If you want user data, you go to the `/api/people` endpoint.

7. HTTP Methods

When you visit an endpoint, you have to tell the server what you want to do. You do this using HTTP methods:

• GET: Read or retrieve data.
• POST: Create new data.
• PUT: Update existing data completely.
• PATCH: Update existing data partially.
• DELETE: Remove data.

8. JSON (JavaScript Object Notation)

APIs need a format to send data that is easy for humans to read and easy for machines to parse. JSON is the standard format for REST APIs.

It uses key-value pairs:

{
  "name": "Rahim Ahmed",
  "age": 21,
  "isStudent": true,
  "courses": ["Math", "Science"]
}

9. Headers

Headers are hidden pieces of information sent along with your HTTP request or response. They contain metadata, like telling the server what type of data you are sending (`Content-Type: application/json`) or proving who you are (`Authorization`).

10. Status Codes

When the server responds, it includes a 3-digit number called a status code to tell you what happened.

• 200 OK: The request was successful.
• 201 Created: Data was successfully created (used with POST).
• 400 Bad Request: You sent bad data or missed a field.
• 401 Unauthorized: You need to log in / provide a valid token.
• 403 Forbidden: You are logged in, but you don't have permission (e.g., you are a USER, but trying to do an ADMIN action).
• 404 Not Found: The endpoint or data does not exist.
• 500 Internal Server Error: The server crashed.

11. CRUD

CRUD is an acronym for the four basic operations you can perform on data:

• Create (POST)
• Read (GET)
• Update (PUT/PATCH)
• Delete (DELETE)

12. Authentication

Authentication answers the question: "Who are you?". In this API, we demonstrate two approaches:

Bearer Tokens

When you log in with your email/password via the API, the server returns a temporary "Token". You send this token in the header of future requests.

Authorization: Bearer YOUR_TOKEN_HERE

API Keys

An API key is a long-lasting secret string you generate in your dashboard. It is often used for server-to-server communication.

X-API-Key: pk_live_xxxxxxxxxxxxxxxxx

13. Authorization (Users vs Admin)

Authorization answers the question: "What are you allowed to do?".

In our API, if you fetch a person's profile without logging in (Public), you only see their `name` and `university`. If you are logged in as a normal `USER`, you see slightly more details (`email`, `age`, `bio`). If you are logged in as an `ADMIN`, you see everything, and you are allowed to Delete/Update users.

14. Error Handling

When an error occurs, this API always returns a consistent JSON structure so your code doesn't break:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication token is required."
  }
}

15. JavaScript Fetch

To use this API in a real frontend application, you will use JavaScript's `fetch()` function.

Simple GET Request

const response = await fetch("/api/public/people");
const data = await response.json();
console.log(data);

Authenticated POST Request

const response = await fetch("/api/people", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_TOKEN"
  },
  body: JSON.stringify({
    name: "New Person",
    email: "new@example.com"
  })
});

Endpoint Reference

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Rahim Ahmed",
      "department": "Computer Science",
      "university": "RUET"
    }
  ]
}

{
  "email": "student@example.com",
  "password": "password123"
}

{
  "success": true,
  "data": {
    "token": "a1b2c3d4e5f6...",
    "role": "USER"
  }
}

Authorization: Bearer YOUR_TOKEN

{
  "success": true,
  "data": {
    "id": 2,
    "name": "Test Student",
    "email": "student@example.com",
    "role": "USER",
    "created_at": "2023-01-01 10:00:00"
  }
}

X-API-Key: pk_live_your_key_here

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Rahim Ahmed",
      "email": "rahim@example.com",
      "age": 21,
      "department": "Computer Science",
      "university": "RUET",
      "bio": "Computer Science student..."
    }
  ]
}