Introduction to Web Services and APIs

TL;DR

Web services let different computer programs talk to each other over the internet. APIs are the rulebooks defining how these conversations happen, acting like a menu for what you can ask for. Together, they enable countless apps to share data and features seamlessly.

1. The Mental Model

Think of web services as restaurants. You, a customer (your app), want food (data or a specific function). An API is the menu: it lists what dishes are available, what ingredients you need to order them, and what you'll get back.

2. The Core Material

At its heart, a web service is a piece of software that makes its functions or data available to other programs over the internet. Instead of you running a program directly on your computer, you send a request to a web service running on another computer (a server), and it sends a response back.

APIs (Application Programming Interfaces) are the agreed-upon rules and specifications that web services follow. They dictate how one program should ask another program for information or to perform an action. Without an API, two programs wouldn't know how to understand each other.

Most modern web services and APIs use HTTP (the same protocol your web browser uses) to send requests and responses. They often exchange data in formats like JSON (JavaScript Object Notation) or XML. JSON is very popular because it's lightweight and easy for both humans and computers to read and write.

Here's a simple flow of how you might interact with an API:

graph TD
    A["Your Application"] --> B{"Send HTTP Request"};
    B --> C["Web Service (Server)"];
    C --> D{"Process Request & Data"};
    D --> E["Generate HTTP Response"];
    E --> F["Your Application"];
    F --> G["Use Received Data/Result"];

Types of APIs

Photo by Stanislav Kondratiev on Pexels

While there are many specific styles, the most common type you'll encounter today are RESTful APIs (often just called REST APIs).

• REST (Representational State Transfer) is an architectural style, not a protocol. It uses standard HTTP methods (like GET, POST, PUT, DELETE) to interact with resources (like "users," "products," or "orders") that are identified by unique URLs.
  • GET: Request data from a specific resource (e.g., GET /users/123 to get user 123's info).
  • POST: Send data to create a new resource (e.g., POST /users with new user data).
  • PUT: Update an existing resource (e.g., PUT /users/123 with updated info for user 123).
  • DELETE: Remove a resource (e.g., DELETE /users/123).

3. Worked Example

Let's say you're building a weather app. You don't want to run your own weather stations; you want to get weather data from a service like OpenWeatherMap. They provide an API.

To get the current weather for London, you might make a request like this:

GET https://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_API_KEY

Here:
* GET is the HTTP method.
* https://api.openweathermap.org/data/2.5/weather is the endpoint (the specific URL for the weather resource).
* q=London and appid=YOUR_API_KEY are query parameters that provide specific instructions (location and your unique access key).

The web service would then send back a JSON response similar to this (simplified):

{
  "coord": {
    "lon": -0.13,
    "lat": 51.51
  },
  "weather": [
    {
      "id": 800,
      "main": "Clear",
      "description": "clear sky",
      "icon": "01d"
    }
  ],
  "main": {
    "temp": 285.55,
    "feels_like": 284.87,
    "humidity": 70
  },
  "name": "London",
  "dt": 1678886400
}

Your app would then parse this JSON to extract main.temp (temperature), weather[0].description (weather conditions), and name (city name) to display to your user.

4. Key Takeaways

• Web services are programs that offer features or data over the internet.
• APIs are the standardized instructions for how to communicate with a web service.
• Most web services use HTTP for communication and JSON for data exchange.
• RESTful APIs are very common and use HTTP methods like GET, POST, PUT, and DELETE.
• An API endpoint is a specific URL that your application sends requests to.
• You often need an API key to access web services for authentication and tracking.
• The response from a web service is typically structured data that your app can parse and use.

5. Now Try It

Find a publicly available API (like one from GitHub, OpenWeatherMap, or a simple "Chuck Norris Jokes" API). Read its documentation to understand one specific endpoint and what data it expects/returns. Then, use an online tool like Postman or a simple curl command in your terminal to send a GET request to that endpoint and view the JSON response. Your success is when you can clearly identify specific data points (e.g., a joke, a user's name, the temperature) within the received JSON.