---
title: "🚀 APIs — A Super‑Beginner‑Friendly Guide"
source: Panaversity Learn Agentic AI
source_url: https://github.com/panaversity/learn-agentic-ai
licence: Apache-2.0
domain: agentic-ai
subdomain: panaversity-agentic
date_added: 2026-04-25
---

## 🚀 APIs — A Super‑Beginner‑Friendly Guide

### 1. What **is** an API, really?

| **Big Idea** | **Plain‑English Explanation** |
| --- | --- |
| **API** = *Application Programming Interface* | A set of rules that lets one piece of software talk to another. |
| Think **“menu in a restaurant.”** | You don’t walk into the kitchen; you point at the menu, the waiter brings your food. The kitchen can change ovens or recipes and you never need to worry! |

### 🍔 More everyday analogies

| Situation | “Kitchen” | “Waiter / API” | “You (Client)” |
| --- | --- | --- | --- |
| Weather app | Weather company’s servers | Weather API | Your phone |
| Ride‑hailing app | Uber/Lyft backend | Trip‑booking API | Rider’s app |
| Online store checkout | Stripe / PayPal | Payment API | Store website |

---

### 2. What does an API **look** like in practice?

Below are three tiny **real‑world** requests you can try in Postman (or even your browser for the GET examples).

> Tip for total beginners:
> 
> 
> Postman is a free desktop app that lets you craft requests and see the raw responses. After you click **Send**, Postman can even show you ready‑made code snippets in **Python, JavaScript, curl, etc.** (Look for the “</>” button).
> 

| # | Real‑world task | Request type | Demo URL (no account needed) | Quick Postman steps |
| --- | --- | --- | --- | --- |
| 1 | Get today’s weather for London | GET | https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12&current_weather=true | 1. New request → GET2. Paste URL → Send |
| 2 | Fetch a random cat fact | GET | https://catfact.ninja/fact | 1. New request → GET2. Paste URL → Send |


---

### 3. OpenAI’s **Chat Completions API** (stateless)

> “Every time you call me, remind me who said what so far.”
> 
- You bundle the **entire conversation history** into each request.
- Great when **you** want full control over memory, ordering, and custom logic.

```python
from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role":"user","content":"What's the capital of France?"}]
)
print(response.choices[0].message.content)   # ➜ Paris

```

---

### 4. OpenAI’s **Responses API** (stateful, tool‑ready)

> “I’ll remember our chat and fetch info for you if needed.”
> 
- You send **just the new user input**; the server stores history for you.
- Built‑in “superpowers” (tools) you can switch on per call:
    - 🔍 Web search
    - 📂 File retrieval
    - 🖥️ Code interpreter
    - 🖼️ Image generation

```python
from openai import OpenAI
client = OpenAI()

# 1️⃣ Ask with a tool & store memory
r1 = client.responses.create(
    model="gpt-4o-mini",
    input="Search the latest AI news in healthcare.",
    store=True,
    tools=[{"type":"web_search_preview"}]
)

# 2️⃣ Follow‑up (no need to resend history)
r2 = client.responses.create(
    previous_response_id=r1.id,
    input="Summarize those findings in bullet points."
)

print(r2.response.text)

```

---

### 5. Quick side‑by‑side comparison

| 🔍 Feature | **Chat Completions** | **Responses** |
| --- | --- | --- |
| Memory | ❌ *Stateless* — you attach past messages every time | ✅ *Stateful* — server remembers |
| Built‑in tools | Manual (function calling) | One‑line opt‑in |
| Typical use | Simple chat, fine‑tuned control | Smart assistants, research bots |
| Follow‑ups | Include `messages=[…]` again | Just pass `previous_response_id` |
| Boilerplate code | More | Less |

---

### 6. “Which one should I start with?”

| Goal | Best pick |
| --- | --- |
| Learn the basics of how LLMs reply | **Chat Completions** (because you see the whole “message sandwich”) |
| Build a quick research assistant with memory + web search | **Responses** |
| Integrate **your own** custom function tools | **Chat Completions** (today) |
| Keep server‑side state ultra‑simple | **Responses** |

> Bottom line: If you’re experimenting or learning concepts → start with Chat Completions.
> 
> 
> If you want a ready‑made agent that can remember and fetch things for you → jump to **Responses**.
> 

---

## Bonus - Next steps for the curious

1. **Try the weather API** above in Postman, then click “Code” ➜ copy the *Python requests* snippet into a `.py` file and run it.
2. Swap out the URL for another public API (e.g., `https://catfact.ninja/fact`).
3. Once comfy, repeat the same flow with the OpenAI Chat Completions endpoint: Postman → “POST” → `https://api.openai.com/v1/chat/completions`.
