Welcome to Pokémon REST Academy

Lesson 1.1: What is a URL and URI?

To understand the difference between a URL and a URI, let’s use a real-world analogy:

1. What is a URI?

URI stands for Uniform Resource Identifier. It’s the umbrella term for anything that identifies a resource (a web page, image, document, or even an abstract concept). A URI can identify something by name, location, or both.

2. What is a URL?

URL stands for Uniform Resource Locator. This is the most common type of URI—the one you use every day in your browser. A URL tells you how to get to a resource (the “locator” part) and always includes a protocol (like http:// or https://).

Key Rule: All URLs are URIs, but not all URIs are URLs.

3. The Third Player: URN

There’s another type of URI called a URN (Uniform Resource Name). For example: urn:isbn:0451450523 is a unique code for a specific book. It identifies the book forever, even if the website or bookstore changes. It’s a name (URI), but not a locator (URL).

Why do we use both?

• URLs are practical. We use them because things on the internet move. If a website moves to a new server, its address (URL) changes.
• URIs (specifically URNs) are used when we need a permanent way to talk about something regardless of where it is stored.

When you look at a website address in your browser, you’re looking at a URL. That string is made up of several distinct “building blocks,” each with a specific job.

The Anatomy of a URL

Let’s use this example: https://www.example.com:443/blog/article?id=10#comments

1. The Protocol (Scheme) — https://
   This tells the computer how to communicate.
   
   • HTTP/HTTPS: The standard for websites. The “S” stands for “Secure” (like sending your mail in a locked box).
   • FTP: Used for transferring files.
   • Mailto: Used to open your email app.
2. The Domain (Hostname) — www.example.com
   This is the name of the server you want to visit.
   
   • Top-Level Domain (TLD): The .com, .org, or .edu part.
   • Subdomain: The www or blog part before the main name.
3. The Port — :443
   You rarely see this because your browser fills it in automatically. If the domain is the “building address,” the port is the specific door you enter through.
   
   • Websites usually use port 80 (HTTP) or 443 (HTTPS).
4. The Path — /blog/article
   This points to the specific file or folder on the server. It’s like the folders on your own computer.
5. The Query — ?id=10
   This provides extra information to the website. It always starts with a ?.
   
   • If you search for “shoes” on Google, the URL will have something like ?q=shoes.
6. The Fragment (Anchor) — #comments
   This is a bookmark. It tells your browser to scroll to a specific part of the page (like the “Comments” section).

Lesson 1.2: What is an HTTP Request/Response?

To understand HTTP Requests and Responses, think of a restaurant:

• You (the Client): You are the customer sitting at the table.
• The Server: This is the kitchen where all the food (data) is kept.
• HTTP: This is the Waiter. The waiter is the messenger who carries your order to the kitchen and brings the food back to your table.

1. The HTTP Request (Ordering your food)

When you type a URL or click a button, your browser sends a Request message. Using the PokéAPI (a real database of Pokémon info), a request to see Pikachu's data looks like this:

GET /api/v2/pokemon/pikachu HTTP/1.1
Host: pokeapi.co
User-Agent: Chrome/123.0
Accept: application/json
                    

2. The HTTP Response (The Kitchen's Reply)

Once the server receives your request, it processes it and sends back a Response:

{
  "name": "pikachu",
  "height": 4,
  "weight": 60,
  "abilities": ["static", "lightning-rod"]
}
                    

3. Summary of the Handshake

Common "Status Codes" You Might See

• 2xx (Success): "I got it, here you go!"
• 3xx (Redirection): "That's not here anymore, go to this other desk."
• 4xx (Client Error): "You made a mistake" (e.g., a typo in the URL).
• 5xx (Server Error): "The kitchen is on fire!" (The server crashed).

Lesson 1.3: What is JSON?

Think of JSON (JavaScript Object Notation) as a simple, digital grocery list or a standardized form for computers to share information.

Before JSON, computers had a hard time "talking" to each other because they all used different formats. JSON was created as a universal language that is easy for humans to read and easy for computers to understand.

1. The "Key-Value" Concept

The secret to JSON is the Key-Value Pair. Imagine you are looking at a Pokémon card for Bulbasaur:

• The Key: The label or category (like "Name", "Type", or "Weight").
• The Value: The actual information next to the label (like "Bulbasaur", "Grass", or "15 lbs").

In JSON, we write it like this: "name": "bulbasaur"

2. How JSON is Structured

JSON follows a few very strict rules to keep things organized. Here’s a simplified response from the PokéAPI:

{
  "id": 1,
  "name": "bulbasaur",
  "is_legendary": false,
  "types": ["grass", "poison"]
}

• Curly Braces { } hold Objects: Like the physical Pokémon card. Everything inside belongs to one "thing" (one Pokémon).
• Square Brackets [ ] hold Lists (Arrays): If a Pokémon has more than one type, we put them in a list inside square brackets.
• Colons : Separate Keys and Values. "name" : "bulbasaur" means "The name is Bulbasaur."
• Commas , Separate items. Like a grocery list, you use a comma to say "here is the next piece of info."

3. Data Types: What can a "Value" be?

In the PokéAPI, the "Values" come in different flavors:

• String (Text): Always inside quotation marks.
  "name": "bulbasaur"
• Number: No quotes needed.
  "weight": 69
• Boolean (True/False): A simple yes/no switch.
  "is_default": true
• Array (List): Multiple values grouped together.
  "abilities": ["overgrow", "chlorophyll"]

4. Why is JSON so popular?

Imagine if every doctor in the world used a completely different medical form. It would be chaos to share records! JSON is the "Standard Form" of the internet. Because the PokéAPI provides data in JSON format, any programmer in the world—whether they are building a phone app, a website, or a video game—can easily "read" the Pokémon data and display it to you.

Lesson 2.1: What is a Resource and Endpoint?

To understand Resources and Endpoints, imagine you are visiting a massive Library.

1. The Resource: The "Noun"

A Resource is the actual thing or data you want to talk about. In a library, resources are the books, magazines, or DVDs. In the digital world, a resource is a piece of information like a "User Profile," an "Invoice," or a Pokémon.

In the PokéAPI, the main resources are:

• Pokémon (e.g., Pikachu, Bulbasaur)
• Abilities (e.g., Static, Overgrow)
• Items (e.g., Pokéball, Potion)

Key Idea: The Resource is the object itself. It's the "what."

2. The Endpoint: The "Map Location"

An Endpoint is the specific location or "doorway" where that resource can be found. If the Resource is a book, the Endpoint is the specific shelf and row number in the library where you go to get it.

In an API, the endpoint is a specific web address (URL).

3. The Relationship: How they work together

Think of it like a Vending Machine:

• The Resource: The snacks inside (the chips, the soda).
• The Endpoint: The button code you press (like A1 or B4).

When you press the button (the Endpoint), you are telling the machine which snack (the Resource) you want it to drop down to you.

Why do we distinguish between them?

One resource can sometimes be reached by multiple endpoints.

Imagine you want to see your "Recent Orders" on Amazon:

• Endpoint A: .../orders/recent (Shows your orders sorted by date)
• Endpoint B: .../user/123/orders (Shows orders belonging to your specific ID)

In both cases, you are getting the same Resource (your orders), but you used two different Endpoints (paths) to find them.

Lesson 2.2: HTTP Methods (Read-Only First)

If Resources are the "nouns" (the things) and Endpoints are the "addresses" (the locations), then HTTP Methods are the verbs.

They tell the server exactly what action you want to perform on a resource.

The Restaurant Analogy (Again!)

• GET: You ask the waiter, "Can I see the menu?" (You are retrieving information).
• POST: You tell the waiter, "I’d like to create a new order." (You are adding something new).
• PUT: You say, "I want to change my entire order to something else." (You are replacing what was there).
• PATCH: You say, "Keep the burger, but change the cheese to Swiss." (You are updating a small part).
• DELETE: You say, "Cancel my order." (You are removing it).

The 4 Most Common Methods

1. GET (The "Read" Method)
   This is what your browser does 99% of the time. It asks the server for data without changing anything.
   PokeAPI Example: GET https://pokeapi.co/api/v2/pokemon/ditto
   Result: The server sends you Ditto’s stats. Nothing on the server changes; you just looked at it.
2. POST (The "Create" Method)
   This is used to send new data to a server. Think of it like "posting" a letter or a social media update.
   Example: If you were playing a Pokémon game and you caught a new Pokémon, the game might send a POST request to save that new Pokémon to your collection.
3. PUT & PATCH (The "Update" Methods)
   These are used when you want to change data that already exists.
   PUT (Replace): You send a whole new version of the data. "Replace my old Pikachu with this new one."
   PATCH (Modify): You only send the specific change. "Change my Pikachu's nickname to 'Sparky', but leave everything else the same."
4. DELETE (The "Remove" Method)
   Exactly what it sounds like. It tells the server to get rid of a resource.
   Example: If you "Release" a Pokémon back into the wild, the app sends a DELETE request to remove it from your digital backpack.

Why the PokéAPI only uses GET

If you try to use DELETE on the PokéAPI, it won't work. Why? Because the PokéAPI is a "Read-Only" library. They want you to look at their data, but they don't want you deleting Pikachu from their database for everyone else!

Lesson 3.1: How Real APIs Work (A Trainer's Journey)

This final lesson ties everything together. We'll use a hypothetical "Pokémon Trainer" app to see how a real API operates in practice.

1. The Request Body: The "Digital Package"

In previous lessons, we used GET to look at data. Since we were just "reading," the URL was enough. But for POST, PUT, or PATCH, you are sending data. This data travels in the Request Body.

• Think of the URL as the address on an envelope, and the Request Body as the letter inside.
• GET: You send an empty envelope; the server puts a letter inside and sends it back (Response Body).
• POST/PUT: You put a JSON "form" inside the envelope and send it to the server.

What is a Request Header?

A Request Header is extra information you send along with your request to help the server understand what you want or who you are. Think of it as a sticky note on the outside of your envelope, giving special instructions or showing your ID badge.

• Headers are not part of the main content (body), but travel with every request you make.
• Common headers include Content-Type (what kind of data you're sending), User-Agent (what browser/app you're using), and Authorization (your digital keycard).

In a real API call, headers are sent in a special section of the request, separate from the body and the URL. For example:

POST /trainer/me/capture HTTP/1.1
Host: api.pokeserver.com
Content-Type: application/json
Authorization: Bearer abc123xyz456

{"species": "Pikachu", "level": 5}
                

2. Using the "Trainer API" (Hypothetical)

While the real PokéAPI is "read-only," a real game would have a "Trainer API" where you can actually manage your team. Here are some example actions:

3. Authentication: The "Keycard"

Why can't anyone just delete your Pokémon? Because of Authentication. It's the process of proving who you are. Many APIs require a digital "ID Badge" (token) to let you in.

The Header usually looks like this: Authorization: Bearer abc123xyz456

• When you log in, the server gives you a long string of random characters called a Token. You must include this token in the Header of every request you make. It’s like wearing a backstage pass at a concert.

4. Why Some APIs are Public and Some are Private

• Public (PokéAPI): Like a public library. Anyone can walk in and read the books. No ID is needed because you aren't changing anything.
• Private (Your Bank/Game Account): Like your house. You need a specific key (Token) because the information is sensitive and you have the power to "Move" or "Delete" things.

Summary: The Full API Interaction

Imagine you want to nickname your Pikachu "Bolt":

• The Method: PATCH (You are modifying an existing thing).
• The Endpoint: https://api.pokeserver.com/v1/my-pokemon/25
• The Header: Authorization: Bearer YOUR_SECRET_TOKEN (The "ID Badge").
• The Body: {"nickname": "Bolt"} (The "Letter").
• The Response: The server sends back 200 OK and a Response Body showing the updated Pikachu.