Software Engineering basics - What is an API

1. What is an API?

An API is a set of rules, protocols, and tools that allow one software system (the client) to interact with another software system (the server or provider).

  • Think of it as a contract: “If you send me a request in this format, I’ll respond with data or perform an action.”

  • It hides the internal complexity of a system and exposes only what’s necessary.

Analogy:
Imagine a restaurant:

  • You (the customer) are the client.

  • The kitchen (where food is made) is the server.

  • The waiter (API) is the interface – you tell them what you want (request), and they bring back what you ordered (response).

2. Why APIs are Important

  • Communication: They allow different applications, built on different technologies, to talk to each other.

  • Integration: Enable third-party apps to connect (e.g., a weather app using data from a government weather API).

  • Reusability: Instead of reinventing the wheel, software can reuse services (e.g., Google Maps API for location).

  • Abstraction: Developers don’t need to know the inner details, just how to interact with the API.

3. How APIs Work (Step by Step)

  1. Request: A client application sends a request to the API.

    • The request usually includes:

      • Endpoint (URL): Where to send the request.

      • Method: What kind of action (GET, POST, PUT, DELETE in REST APIs).

      • Headers: Extra info like authentication (API keys, tokens).

      • Body: Data sent with the request (e.g., form data, JSON).

  2. Processing: The server (API provider) receives the request, processes it, interacts with its database or logic, and prepares a response.

  3. Response: The server sends back a response in a structured format (often JSON or XML).

    • Includes:

      • Status code (e.g., 200 OK, 404 Not Found, 500 Server Error).

      • Data payload (e.g., user info, weather data).

4. Types of APIs

  • Web APIs (most common): Communication over the internet (HTTP/HTTPS).

    • REST (Representational State Transfer) – lightweight, widely used.

    • SOAP (Simple Object Access Protocol) – older, XML-based.

    • GraphQL – client can specify exactly what data it needs.

  • Library APIs: Functions exposed by a software library for developers to use.

  • Operating System APIs: Interfaces for apps to use system resources (Windows API, POSIX).

  • Hardware APIs: Allow software to communicate with hardware (camera, sensors).

5. Example of API Communication

Let’s say you’re building a weather app that shows the temperature. Instead of building your own weather service, you use a Weather API.

  • Request (Client → Server):

    GET https://api.weather.com/v1/current?city=London&apikey=12345

    • Method: GET

    • Endpoint: /v1/current

    • Query parameters: city=London, apikey=12345

  • Response (Server → Client):

    {
  "city": "London",
  "temperature": 18,
  "condition": "Cloudy"
}

Your app then displays: “London: 18°C, Cloudy.”

6. Benefits of APIs in System Communication

  • Interoperability: Different systems (written in Java, Python, PHP, etc.) can work together via APIs.

  • Scalability: APIs let systems scale by delegating tasks (e.g., payment handled by Stripe API).

  • Security: APIs can enforce authentication (keys, OAuth tokens).

  • Automation: APIs enable automated workflows (e.g., Zapier connecting Gmail with Slack).

7. Real-World Examples

  • Google Maps API: Apps use it for maps and directions.

  • Stripe/PayPal APIs: Handle online payments.

  • Twitter API: Access tweets, post tweets programmatically.

  • Spotify API: Fetch playlists, control music playback.