API's explained for dummies ( with OpenWeather example )

Beginner's Guide to APIs with OpenWeatherMap Example

Introduction

APIs stand for Application Programming Interface. Here's an analogy to visualize it: Imagine you are at a restaurant and want to get some food. Think of the menu as the API of the restaurant. The menu lists what the restaurant offers, its prices, and other details. The kitchen can be thought of as the system doing the work, while the server delivers the service. You, the user, do not use the kitchen directly; instead, through what is listed on the menu (the API), you make your request, and the service is delivered. APIs are much broader than this analogy, but basically, that's how they function.

APIs are useful because they give us access to various services provided by platforms in a reliable way. For example, if you are creating a WhatsApp chatbot for your business, you'll need APIs for WhatsApp and AI model integration. Or maybe you're building a website to increase visibility for businesses in your locality and want to add a map. Instead of painfully coding your own map system and visuals—which is possible and noble—you can integrate Google's already-made map interface. This principle applies to many other things like emails, database integration, site or app analytics, and payments through platforms like PayPal or Stripe.

How APIs Work (Basic Flow)

Request: Your app sends a request to the API server, usually via HTTP/HTTPS. It includes the endpoint, method, and sometimes parameters.
Processing: The API server processes your request, fetches data, or performs an action (like sending a message or charging a card).
Response: The API sends data back, usually in JSON or XML format.

Example JSON response:

{
  "temperature": 30,
  "condition": "sunny"
}

API Authentication / Security

Most APIs require a key or token to prove you’re allowed to use them. Examples include API keys, OAuth tokens, or JWT (JSON Web Tokens). For example, if you are using Supabase in a project, you'll need your API keys and other important tokens provided by the platform. You might also need to install the supabase-js module if you're building a web platform.

Types of APIs

Web APIs: Communicate over the internet (REST, GraphQL, SOAP).
Library / Framework APIs: Functions you can call inside a programming language.
Operating System APIs: Allow apps to access system features (Windows API, Android API).

Common API Methods (HTTP / Web APIs)

Method	Purpose
GET	Retrieve data from the server
POST	Send data to the server (create something)
PUT / PATCH	Update existing data
DELETE	Delete data

Advantages of Using APIs

Speed: Use existing services without building from scratch.
Scalability: Your app can interact with many services easily.
Flexibility: Combine multiple APIs (maps, payments, notifications) seamlessly.

Example in JavaScript (REST API Call)

Here’s a JavaScript example calling a RESTful API (OpenWeatherMap, a useful weather data API):

fetch('https://api.openweathermap.org/data/2.5/weather?q=Tokyo&appid=YOUR_API_KEY')
  .then(response => response.json())
  .then(data => console.log(data.main.temp))
  .catch(error => console.error(error));

Breaking It Down Line by Line

fetch(...): Built-in JavaScript function to make HTTP requests.
URL: 'https://api.openweathermap.org/data/2.5/weather?q=Tokyo&appid=YOUR_API_KEY'
q=Tokyo → Requests weather in Tokyo
appid=YOUR_API_KEY → Your personal API key for authentication
.then(response => response.json()): Converts the server response from JSON into a JavaScript object
.then(data => console.log(data.main.temp)): Prints the temperature to the console
.catch(error => console.error(error)): Handles errors, like network issues or invalid API keys

Summary:

Makes a request to OpenWeatherMap for Tokyo's weather
Parses the JSON response
Logs the temperature to the console
Handles errors gracefully

Running the Code

Browser Example

Create a file called weather.html:

<!DOCTYPE html>
<html>
<head><title>Tokyo's Weather</title></head>
<body>
  <h1>Weather in Tokyo</h1>
  <p id="temp">Loading...</p>

  <script>
    const apiKey = 'YOUR_API_KEY'; // Replace with your key
    const city = 'Tokyo';
    const url = `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${apiKey}&units=metric`;

    fetch(url)
      .then(response => response.json())
      .then(data => {
        document.getElementById('temp').innerText =
          `Temperature: ${data.main.temp}°C, Condition: ${data.weather[0].description}`;
      })
      .catch(error => console.error('Error:', error));
  </script>
</body>
</html>

Save the file and open it in a browser to see the live weather data.

Node.js Example

If you want to run this in Node.js:

Make sure Node.js is installed
Create weather.js:

const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args));

const apiKey = 'YOUR_API_KEY';
const city = 'Tokyo';
const url = `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${apiKey}&units=metric`;

fetch(url)
  .then(res => res.json())
  .then(data => {
    console.log(`Temperature: ${data.main.temp}°C, Condition: ${data.weather[0].description}`);
  })
  .catch(err => console.error('Error:', err));

Run in terminal:

node weather.js

Output example:

Temperature: 30°C, Condition: clear sky

Try It Yourself: Interactive Weather Demo

Type any city below and click "Get Weather" to see live weather data using the OpenWeatherMap API.

Search This Blog

SmartTechScout