Introduction to API

:dart: Learning Objectives

By the end of this lesson, you will be able to:

• Understand what an API is and how it connects applications
• Read and interpret JSON data format
• Use API endpoints and paths to access data
• Write async functions to fetch data from APIs
• Build forms that make dynamic API requests

:information_source: What is an API? An Application Programming Interface (API) is like a waiter in a restaurant. Just as a waiter takes your order to the kitchen and brings back your food, an API takes requests from one application to another and brings back the data you need.

:wrench: How APIs Help Us

APIs let us access data and features from other applications. Think of them as bridges that connect different apps together!

:iphone: Real-World API Examples

• Twitter API: Display the latest tweets on your website
• Google Maps API: Add custom maps with your favorite locations
• Facebook API: Let users log in with their Facebook account
• Weather API: Show real-time weather on your app
• Pokemon API: Get information about all Pokemon characters

:sparkles: Why Use APIs?

• Free to use: Most APIs don't cost any money
• Ready-made solutions: No need to build everything from scratch
• Easy access: Read and write data without complex setup
• Time-saving: Use existing services instead of creating your own

:package: JSON Format

APIs speak in a special language called JSON. Let's learn how to read it!

:memo: Note JSON stands for JavaScript Object Notation. It's a simple way to organize and send data as text.

Why JSON?

When your browser talks to a server, they can only exchange text messages. JSON helps organize this text so both sides understand what the data means.

:memo: JSON Rules

JSON follows three simple rules:

1. Square brackets [ ] = Lists of things (arrays)
2. Curly braces = Groups of information (objects)
3. Name:value pairs = Labels and their values, separated by commas

Here's what JSON looks like:

:emoji: API Endpoints

An API endpoint is like a website address (URL) where you can request data. It's the front door to the API!

How Endpoints Work

Think of endpoints like addresses:

• Your home has an address where people can find you
• APIs have endpoints where programs can find data

Most endpoints follow this pattern:

:mag: Example: The Bored API

Let's explore a real API endpoint: https://www.boredapi.com/api/

When you visit this endpoint, you see:

{"message": "Bored API"}

This is like knocking on the front door - the API says "Hello, I'm the Bored API!" But to get actual data, you need to ask for something specific using an API path.

:emoji:️ API Paths

API paths tell the API exactly what data you want. They're like asking for a specific item from a menu!

Building a Complete Request

To get data, you combine:

1. Endpoint (the main address)
2. Path (what specific data you want)

Example: https://www.boredapi.com/api/activity

• Endpoint: https://www.boredapi.com/api/
• Path: /activity

When you visit this complete URL, you get:

{
  "activity": "Host a movie marathon with some friends",
  "type": "social",
  "participants": 3,
  "price": 0.1,
  "link": "",
  "key": "5914292",
  "accessibility": 0
}

:bulb: Tip The path /activity tells the Bored API: "Give me a random activity to do!"

:emoji: Testing APIs with Hoppscotch

Let's explore some real APIs! We'll use a tool called Hoppscotch to see API responses clearly.

Getting Started with Hoppscotch

1. Visit https://hoppscotch.io/
2. Copy any API URL from the list below
3. Paste it in the request field
4. Click Send

:memo: Note Troubleshooting: If you see an error, select "Proxy" as the interceptor in settings.

:video_game: Fun APIs to Explore

Try these APIs in Hoppscotch:

• Cat Facts: https://catfact.ninja/fact
  Get random facts about cats!

• Cat Status Codes: https://http.cat/
  See HTTP status codes explained with cat pictures

• Makeup Products: https://makeup-api.herokuapp.com/api/v1/products.json
  Browse makeup product information

• Yes or No: https://yesno.wtf/api
  Get random yes/no answers with GIFs

• Weather API: https://goweather.herokuapp.com/weather/KL
  Check weather for different cities (Documentation)

• Fruits Database: https://www.fruityvice.com/api/fruit/all
  Learn nutrition facts about fruits

• Pokemon API: https://pokeapi.co/api/v2/pokemon/
  Get data about all Pokemon

⏱️ Async Functions

JavaScript has special functions called async functions that handle tasks that take time - like waiting for API data!

async function getData() {
  // fetch data here
}

Why Async?

Imagine you order pizza:

• Without async: You stand at the door doing nothing until the pizza arrives
• With async: You can watch TV, do homework, or play games while waiting

That's exactly how async functions work! Your code keeps running other tasks while waiting for API data.

:bulb: Tip The word "async" is short for "asynchronous" - which means "not at the same time". Your code doesn't freeze while waiting!

:emoji: The Fetch Function

The fetch() function is how we grab data from APIs. Let's see it in action!

Basic Fetch Example

Here's how to fetch cat facts from an API:

let catFact;

async function getCatFact() {
  fetch("https://catfact.ninja/fact")
    .then((response) => response.json())
    .then((data) => {
      catFact = data.fact; // JSON Path for the cat fact
    });
}

How Fetch Works

1. fetch() sends a request to the API
2. .then() waits for the response
3. response.json() converts the text to JSON format
4. We save the data we need

:mag: Finding the Right Data

When the Cat Facts API responds, it sends this JSON:

{
  "fact": "The oldest cat on record was Crème Puff from Austin, Texas, who lived from 1967 to August 6, 2005, three days after her 38th birthday. A cat typically can live up to 20 years, which is equivalent to about 96 human years.",
  "length": 220
}

The JSON contains:

• fact: The actual cat fact (this is what we want!)
• length: How many characters long the fact is (we don't need this)

So we use data.fact to get just the fact:

catFact = data.fact; // Gets only the fact, ignores the length

:memo: Note Pro tip: Use Hoppscotch to explore API responses and find the exact path to the data you need!

:memo: Building Interactive Forms with APIs

Now let's make our APIs interactive! Users can input what they want to search for.

Simple Button Example

For basic APIs like Cat Facts, a simple button works:

<button on:click={getCatFact}>Get Cat Fact</button>

Advanced Form Example

Many APIs let you customize your request. The Bored API lets you choose activity types:

• Base URL: https://www.boredapi.com/api/activity
• With type: https://www.boredapi.com/api/activity?type=education

Available types: education, recreational, social, diy, charity, cooking, relaxation, music, busywork

:rocket: Complete Working Example

<script>
  let activity = "";
  let type = "";

  async function getBoredActivity() {
    fetch('https://www.boredapi.com/api/activity?type=' + type)
      .then((response) => response.json())
      .then((data) => {
        activity = data.activity; // Path for activity
        type = data.type; // Path for type
      });
  }
</script>

<form on:submit|preventDefault={getBoredActivity}>
  <label for="type">Type:</label>
  <input id="type" bind:value={type} type="text" />
  <button type="submit">Get random activity</button>
</form>

<p>Activity: {activity}</p>
<p>Type: {type}</p>

:bulb: Tip Try it yourself! Copy this code to Svelte REPL and experiment with different activity types!

:books: Summary

Let's review what we learned about APIs!

Key Takeaways

• APIs are bridges that connect different applications together
• JSON is the language APIs use to send data (using , [], and name:value pairs)
• Endpoints are addresses where APIs live on the internet
• Paths are specific requests for the exact data you want
• Async functions prevent freezing by handling wait times smartly
• Fetch() grabs the data and converts it to usable JSON
• Hoppscotch helps you test APIs before using them in code
• Forms make APIs interactive by letting users customize requests

:movie_camera: Video Tutorials

Watch these videos to see APIs in action:

:emoji: Practice Time!

1. Explore an API: Pick one API from our list and test it in Hoppscotch
2. Find the data path: Look at the JSON response and identify what data you'd want to use
3. Create a simple app: Use the Cat Facts API to display a random fact with a button
4. Challenge yourself: Build a form that lets users search for Pokemon by name using the Pokemon API

Remember: APIs are everywhere on the internet - from weather apps to social media. Now you know how they work!