API

What is an API?

API stands for Application Programming Interface. An API is a defined interface through which programs can communicate with each other.

Restaurant analogy

Imagine a restaurant:

• You (customer) = Your program
• Waiter = API
• Kitchen = The other program or service

You tell the waiter what you want (API request). The waiter takes your order to the kitchen, which prepares it and returns it through the waiter (API response). You do not need to know how the kitchen works—you only need to know how to communicate with the waiter.

Practical examples

• The weather app on your phone uses a weather service API.
• The “Sign in with Google” button uses Google’s OAuth API.
• Paying with PayPal uses the PayPal API.
• Automatic translation uses the DeepL or Google Translate API.

Types of APIs

Web APIs

The most common type. Programs communicate over the Internet using HTTP/HTTPS.

Example: Your website asks a service through an API: “Give me all blog posts from today.”

The service responds with data (usually in JSON format).

Operating system APIs

Windows, Linux, and macOS provide APIs that allow programs to access storage, open windows, and use network services.

Example: A program wants to save a file → it uses the operating system API instead of accessing the hardware directly.

Library APIs

When you use a programming library (for example, for image processing), you are using that library’s API.

Example: image.resize(800, 600) is an API call provided by the library.

How does a Web API work?

Request

Your program sends an HTTP request to a URL:

GET https://api.example.com/users/123
Authorization: Bearer abc123token

• GET = Type of request (retrieve data)
• URL = Where the API is and what you want
• Authorization = Proof that you are authorized

Response

The server responds with data:

{
  "id": 123,
  "name": "Max Mustermann",
  "email": "max@example.com",
  "created": "2024-01-15"
}

Your program continues processing this data.

HTTP methods

• GET: Retrieve data
• POST: Create new data
• PUT: Update data
• DELETE: Delete data

Examples:

• GET /users → List all users
• POST /users → Create a new user
• PUT /users/123 → Update user 123
• DELETE /users/123 → Delete user 123

REST APIs

REST (Representational State Transfer) is a widely used architectural style for Web APIs.

REST APIs follow several principles:

• Use standard HTTP methods (GET, POST, PUT, DELETE)
• URLs represent resources (/users, /posts, /comments)
• Stateless: Every request contains all required information
• Responses are usually returned in JSON format

Example of a REST API

A blog API following REST principles:

GET /posts → All blog posts
GET /posts/42 → Post with ID 42
POST /posts → Create a new post
PUT /posts/42 → Update post 42
DELETE /posts/42 → Delete post 42
GET /posts/42/comments → Comments for post 42

Authentication

Why?

APIs need to associate requests with an application or a user in order to:

• Prevent unauthorized access
• Enforce rate limits (for example, a maximum of 1,000 requests per hour)
• Perform billing

API keys

The simplest approach: the service gives you a unique key. It usually identifies the calling application, not automatically the individual user.

GET /data?api_key=abc123def456

Problem: If someone steals your key, they can misuse it.

Bearer tokens

A token sent in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens often have an expiration time (for example, one hour) to improve security.

OAuth

The most complex but also the most secure approach. The user authorizes your application with a service without revealing their password to you.

Example: “Sign in with Google” uses OAuth. Your application receives a token that allows it to access Google services.