Fundamentals of APIs and Web Services

TL;DR

APIs (Application Programming Interfaces) let different software talk to each other, like a menu in a restaurant. Web services are a specific type of API that uses web protocols to communicate over the internet. You'll often use APIs to get or send data between applications.

1. The Mental Model

Imagine you want a specific dish at a restaurant. You don't go into the kitchen and cook it yourself; you look at the menu (the API documentation), tell the waiter (the API call) what you want, and they bring it to you (the API response).

2. The Core Material

APIs are essentially sets of rules and protocols that allow different applications to communicate. They define how software components should interact. Think of them as a contract: if you send data in this format, I'll give you data back in that format.

What's an API?

Photo by Ann H on Pexels

An API specifies how you can request services from another piece of software. It defines the methods you can use and the data formats it understands. For instance, a weather API might have a method get_current_weather that takes a location as input and returns temperature, humidity, and conditions.

What's a Web Service?

Photo by panumas nikhomkhai on Pexels

A web service is an API that's accessible over the web. This means it uses standard web protocols like HTTP/HTTPS to communicate. Most APIs you'll interact with today are web services, often following REST principles.

How do they communicate?

Photo by Ann H on Pexels

When you make an API request to a web service, you're essentially sending an HTTP request (like when your browser loads a webpage) to a specific URL (called an endpoint). This request usually includes:
* Method (Verb): What you want to do (e.g., GET to retrieve data, POST to create new data, PUT to update, DELETE to remove).
* Headers: Metadata about the request (e.g., Content-Type for the data format, Authorization for your access key).
* Body (Payload): The actual data you're sending, especially for POST or PUT requests.

The server then processes your request and sends back an HTTP response, which includes:
* Status Code: A number indicating the success or failure of the request (e.g., 200 OK, 404 Not Found, 500 Internal Server Error).
* Headers: Metadata about the response.
* Body: The data you requested, usually in a structured format like JSON or XML.

graph TD
    A["Your Application (Client)"] --> B{HTTP Request};
    B -- GET /weather?city=London --> C["Web Service (Server)"];
    C --> D{Process Request};
    D -- Query Database/Logic --> E["Data Source"];
    E --> D;
    D --> F{HTTP Response};
    F -- 200 OK, JSON Data --> A;

JSON (JavaScript Object Notation)

Photo by RealToughCandy.com on Pexels

JSON is a lightweight data-interchange format. It's easy for humans to read and write, and easy for machines to parse and generate. Most web services use JSON for sending and receiving data.

Here's an example of JSON data:

{
  "city": "London",
  "temperature": {
    "celsius": 15,
    "fahrenheit": 59
  },
  "conditions": "Partly Cloudy",
  "humidity": 75
}

3. Worked Example

Let's say you want to get the current weather for New York City using a hypothetical weather API. You'd typically use a GET request to an endpoint.

Request:
You'd make an HTTP GET request to an endpoint like:
https://api.example.com/weather?city=New%20York

You might send some headers, like an API key for authentication:
Authorization: Bearer YOUR_API_KEY

Response (if successful, HTTP Status 200 OK):
The server would return a JSON response in the body, like this:

{
  "city": "New York",
  "temperature": {
    "celsius": 20,
    "fahrenheit": 68
  },
  "conditions": "Clear",
  "humidity": 60,
  "wind_speed_kmh": 15
}

Your application would then parse this JSON and display "The current temperature in New York is 20°C with clear skies."

4. Key Takeaways

• APIs define how software components interact, acting as a contract.
• Web services are a type of API accessible over the internet using standard web protocols like HTTP.
• You make requests to specific endpoints using HTTP methods like GET, POST, PUT, DELETE.
• The server responds with a status code and often a JSON body containing the requested data.
• JSON is a common, human-readable format for data exchange in web services.

• API documentation tells you exactly what requests to make and what responses to expect.

• Common Mistake 1: Forgetting to include necessary headers, like authentication tokens.

• Common Mistake 2: Not checking the HTTP status code in the response to ensure the request was successful.
• Common Mistake 3: Misunderstanding the data format expected by the API (e.g., sending XML when JSON is required).
• Common Mistake 4: Calling the wrong HTTP method for the intended action (e.g., using GET when you should POST).

5. Now Try It

Find a public API (like the "JSON Placeholder" API for fake data, or a public weather API). Read its documentation to understand how to get a list of posts or the current weather for a city. Then, use a tool like Postman, Insomnia, or even your browser's developer console (for GET requests) to make a request and observe the JSON response. What was the status code? What data did you get back?