KAHIBARO
Discord Login Register ☰
☰

What Is an API?

Table of Contents

Understanding APIs

An API is a way for two programs to talk to each other.

The full name is Application Programming Interface. In backend development you will work with APIs all the time, both consuming them and building them.

This chapter explains what that really means, in simple, concrete terms.

Interface: The Core Idea

You already know interfaces from daily life.

In all of these:

An API is the same idea, but for software.

You do not need to know how it does the work internally.

Key Idea:
An API is a contract that describes how to use a piece of software from the outside, without knowing its internal implementation.

Application, Programming, Interface

Let us break down the term:

WordMeaning in “API”
ApplicationAny program or service, for example a web server, payment system, database
ProgrammingUsed by programs, not by humans directly
InterfaceThe defined way to interact, like buttons, functions, or endpoints

An API is not a graphical user interface (GUI). You usually do not click it with a mouse. Instead, your code or another application interacts with it, often over HTTP, using requests and responses.

A Simple Real-World Analogy: Restaurant Menu

Imagine a restaurant:

You:

  1. Read the menu (API documentation).
  2. Choose an item, for example "Cheeseburger".
  3. Tell the waiter your order (request).
  4. The kitchen prepares food (internal logic you do not see).
  5. The waiter brings back the dish (response).

You do not:

You simply use the interface they provide.

In software, your application:

  1. Reads the API docs.
  2. Sends a request to a URL, for example /orders.
  3. The backend service does some work.
  4. The backend sends back a response with data, for example JSON.

What Does an API Look Like?

There are many kinds of APIs, but in web backends we mostly care about web APIs that use HTTP.

Here is an example of a very simple HTTP API, for a weather service.

You, as a client, might send a request:

http 
GET /weather?city=London HTTP/1.1
Host: api.example.com
Accept: application/json

The server might respond:

http 
HTTP/1.1 200 OK
Content-Type: application/json
{
  "city": "London",
  "temperature_c": 18.5,
  "conditions": "Cloudy"
}

You do not know how it finds the temperature. It might call other services, read from a database, or do complex calculations. The API hides that complexity behind a simple contract:

Why APIs Matter in Backend Development

As a backend developer, you will:

APIs let different systems:

Public, Private, and Partner APIs

APIs are used in different contexts. The contract idea is the same, but the audience changes.

Public APIs

Use case: Third-party developers build apps that integrate with these platforms.

Private (Internal) APIs

Use case: Structure a large system into well-defined parts with clear contracts.

Partner APIs

Use case: Two companies integrate their systems in a controlled way.

Types of APIs (High Level)

You will learn specific types later in the course, but here is a quick overview of common web API styles:

TypeKey ideaTypical format
RESTResources with URLs and HTTP methodsJSON over HTTP
GraphQLClients ask exactly for the data they needJSON over HTTP
gRPCBinary messages, very fast, often internalProtocol Buffers
WebSocketsTwo-way, real-time communicationText / binary

In this section of the course we focus on REST APIs, which use HTTP methods like GET, POST, PUT, and usually JSON.

Example: A Simple Library API

Imagine we are building a backend for a small library system.

We might design a simple API like this:

OperationHTTP MethodURLDescription
List all booksGET/booksGet a list of all books
Get one bookGET/books/{id}Get details of one book
Add a new bookPOST/booksCreate a new book
Update a bookPUT/books/{id}Replace info for one book
Delete a bookDELETE/books/{id}Remove a book from the system

Example request to list all books:

http 
GET /books HTTP/1.1
Host: api.library.com
Accept: application/json

Example response:

http 
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "id": 1,
    "title": "Clean Code",
    "author": "Robert C. Martin",
    "year": 2008
  },
  {
    "id": 2,
    "title": "Design Patterns",
    "author": "Erich Gamma",
    "year": 1994
  }
]

Again, the API does not show:

It only exposes what you can do and what you get back.

API as a Contract

Think of an API like a legal contract between:

The contract includes things like:

If the provider and consumer both respect the contract, everything works smoothly.

Important Rule:
Changes to an API must not silently break existing clients. You must manage changes carefully, often with versioning (for example /v1/..., /v2/...).

You will learn about API versioning and documentation in later chapters of the REST APIs section.

APIs and Abstraction

One of the main purposes of an API is abstraction.

Abstraction means:

Example:

http 
POST /payments HTTP/1.1
Content-Type: application/json
{
  "amount": 49.99,
  "currency": "USD",
  "card_token": "tok_12345"
}

And receives:

json 
{
  "payment_id": "pay_98765",
  "status": "successful"
}

The API user sees a simple payment operation, not the full complexity.

This abstraction:

Common Misconceptions about APIs

“An API is a database”

Not exactly. A database is where data is stored. An API is a way to interact with a system.

An API might give you access to data stored in a database, but it can also:

“An API is just a URL”

A single URL is not an entire API. An API is the whole set of endpoints and rules.

You might have:

Together with the required JSON bodies, headers, and behavior, these form an API for user management.

“APIs are only for the web”

No. APIs exist in many forms:

In this course we focus on web APIs, especially RESTful APIs, because they are central to backend development.

A Small End-to-End Example

Let us put it all together.

You are building a Todo List web application.

  1. The user opens https://todo.example.com in the browser.
  2. The frontend JavaScript application loads.
  3. It wants to show the current user’s tasks, so it calls your backend API:
http 
   GET /api/tasks HTTP/1.1
   Host: api.todo.example.com
   Accept: application/json
   Authorization: Bearer <token>
  1. Your backend:
    • Validates the token
    • Looks up the user in the database
    • Fetches the user’s tasks
    • Sends back:
http 
HTTP/1.1 200 OK
Content-Type: application/json
[
  {"id": 1, "title": "Buy milk", "completed": false},
  {"id": 2, "title": "Study backend development", "completed": true}
]

The browser then:

Your backend API:

Summary

Views: 15

Comments

Please login to add a comment.

Don't have an account? Register now!

© 2025 Kahibaro
Visitors: 3098 / 24h
Impressum / Imprint
Datenschutz / Data Policy