Skip to content
Ameen Abozaid
Englishالعربية
PublishedBEG-053-L01

What an API is

  • Lesson 1 of 6
  • 10 min read
  • Beginner
On This Lesson 11 topics

Lesson Overview

In the previous module you learned how HTTP requests and responses look, and what JSON is. Now we put those pieces to work. This module is about APIs: the way one program asks another program to do something, or to hand over some data.

The picture we use for the whole module is a restaurant. You sit at a table and read a menu. A waiter carries your order to the kitchen and brings back the dish. You never walk into the kitchen, and you do not need to know how the chef cooks. The menu is the API: it lists what you may ask for, in what form, and what you will get back.

This lesson answers four questions. What is an API? Why do providers hide the inside? What is a web API? And why will almost every backend job you take involve building or calling one?

This lesson builds on Module BEG-052 (HTTP requests, responses, status codes, and JSON). No new tools are needed: you will only read requests and responses.

Learning Objectives

By the end of this lesson you will be able to:

  • Explain what an API is in plain words, with the restaurant analogy.
  • Say who the client and the provider are in a given situation.
  • Explain why the inside of the provider stays hidden behind the API.
  • Describe a web API: it is used over HTTP and usually answers in JSON.
  • Recognize which parts of a request are the "menu" (the contract) in a real API call.
  • Name three kinds of software that call web APIs.

Written Explanation

An API is a contract

API stands for application programming interface. The Mozilla (MDN) glossary describes it as a set of features and rules in a piece of software that lets other software interact with it, as opposed to a human using a screen. It is a contract between the program that offers the features and the programs that use them.

Two roles appear in every API conversation:

RoleRestaurantSoftware
ClientThe guest who ordersThe program that makes the request (a phone app, a website, another service)
Provider (or server)The kitchenThe program that holds the data and logic and answers
APIThe menu and the waiterThe list of allowed requests, and the way to send them

A program can be a client in one conversation and a provider in another. A shop's backend answers requests from the shop's mobile app (it is the provider), and it calls a payment company's API to take the card payment (it is the client).

What the contract says

A good API tells you, for each thing you may ask:

  1. How to ask: where to send the request and with which method.
  2. What to send: any parameters or body.
  3. What you get back: the shape of the answer, and the status codes for success and failure.

Everything else is the provider's private business. This is the rule of the restaurant: you may order a dish from the menu, but you may not walk into the kitchen and open the fridge.

Why hide the inside?

Hiding the inside is a feature, not a limitation.

  • Safety. The client cannot read or change the database directly, so it cannot damage data or see data it should not see. The provider checks every request first.
  • Freedom to change. The provider can switch databases, rewrite its code, or move servers. As long as the menu stays the same, no client notices.
  • Simplicity for the client. The client only needs to learn the menu, not how the kitchen works.

Web APIs

APIs exist inside programs too: Java's own libraries are APIs, and so are the methods of a class you wrote. In this module we mean a web API: the client and the provider are on different machines and talk over HTTP (Module BEG-052). The request carries a method, a URL, headers, and sometimes a body. The response carries a status code, headers, and usually a body.

Most web APIs send and receive JSON. So a web API call is exactly what you already know, with a purpose: the URL and method are the order, and the JSON is the dish.

The architecture looks like this:

text
 client (phone app, website, script)
        |
        |  HTTP request:  GET /products/1
        v
 +--------------------+
 |   provider: API    |  <- the menu: the only part the client sees
 +--------------------+
        |   (private: code, rules, database)
        v
     database
        |
 HTTP response: 200 OK + JSON body goes back to the client

The client sees only the API layer. Whether a database sits behind it, which one, and how the data is stored are none of its business.

Who uses web APIs?

  • Mobile apps. A banking app on your phone has no database of accounts; it asks the bank's API.
  • Websites. Many sites load a page shell first, then fetch data from an API and draw it.
  • Other services. One backend service calls another (payments, email, maps, weather).
  • Scripts and tools. A short script or a command-line tool can call an API too. You will do this with curl and Postman in this module.

Public and private APIs

Some APIs are open to anyone (public APIs, often with usage limits). Others are only for the provider's own apps or for paying partners, and need credentials. In the later lessons we will use a public practice API that needs no sign-up, so you can experiment freely.

Documentation is the menu printed

Providers publish API documentation: a page that lists every endpoint, its parameters, and example responses. Reading documentation is a core skill: when you meet a new API you will not guess; you will read the menu. We practise this in Lessons 3 to 6.

Examples

Example 1: Simple. The weather app

A weather app on your phone shows today's temperature. The phone is the client. It sends an HTTP request to a weather provider, which answers with JSON such as {"city":"Cairo","temp":31}. The app turns that into a nice display.

Notice what is not happening: the phone does not connect to the weather company's database, and it does not know how the temperature was measured. It only used the menu.

Example 2: Practical. One real request and response

Here is a real call to a public practice API called DummyJSON. We ask for product number 1, and use select so the answer stays short (we will explain every part in later lessons).

bash
curl -s "https://dummyjson.com/products/1?select=title,price"

Real output:

json
{"id":1,"title":"Essence Mascara Lash Princess","price":9.99}

Map it to the restaurant:

PartMeaning
https://dummyjson.comThe restaurant's address (the provider)
/products/1The dish we ordered: product 1
?select=title,priceA request to the kitchen: "only these two fields, please"
The JSONThe dish on our table

We never saw the provider's database. We only read from the menu: its documentation says that GET /products/{id} returns one product.

Example 3: Realistic. An online shop uses three APIs

You open a shop's mobile app and buy a book.

  1. The app calls the shop's own API to list books and to create the order. The shop's team builds and owns this API. This is the kind of API you will build in the Junior level.
  2. The shop's backend calls a payment provider's API to charge the card. It is a client here.
  3. The backend calls an email provider's API to send the receipt.
text
mobile app --API--> shop backend --API--> payment company
                         |
                         +-----API-----> email company

Each arrow is an HTTP conversation with a documented contract. The shop's team does not need to know how the payment company stores cards. That separation lets teams and companies work independently.

Backend Insight

As a backend developer you are the person who writes the menu and runs the kitchen. Your decisions about the API (names, shapes, status codes) become a promise to every client. Changing a name in your Java code is cheap; changing a name in a published API breaks every app that uses it. So API design deserves care, and it is the reason this module spends a whole lesson on sketching endpoints before any code exists.

Also note the safety rule: a backend must never trust a client. Every request must be checked on the server, because the API is the only door in.

Common Mistakes

  • Thinking an API is a database. A database stores data. An API is a controlled way to ask a program for data. The program may or may not use a database.
  • Thinking an API is a library of code only. Java classes have APIs too, but in this module "API" means a web API over HTTP.
  • Thinking the client can see how the provider works. It cannot, and that is the point.
  • Forgetting both roles. A backend is often a provider and a client at once.
  • Guessing instead of reading the documentation. Wrong paths and parameters give 404 or 400 errors; the docs tell you the right ones.

Exercises

Level A: Foundation

  1. In your own words, in three sentences, explain what an API is to a friend who does not program. Use the restaurant picture.
  2. A food-delivery app shows nearby restaurants. Which is the client and which is the provider? Where does the database sit?
  3. True or false: "A client can read the provider's database directly if it knows the table names." Explain.

Level B: Application

  1. Take the real call in Example 2. Change the product number to 2 and run it yourself in a terminal (you will learn curl fully in Lesson 4; for now just copy the command). What changed in the answer?
  2. Name three advantages for a provider of keeping its database behind an API.
  3. A hotel-booking website shows weather and takes payments. List the APIs it probably calls as a client, and the API its own mobile app probably calls.

Level C: Challenge

  1. A provider renames the field price to cost in its API with no warning. Describe what happens to apps that use the API, and what a careful provider would do instead (give one idea).
  2. Draw (text is fine) a diagram of a library system: a mobile app for members, a staff website, and a backend with a database. Mark every place where an API sits.
Show solutions
  1. An API is a menu of requests that one program may make to another. The provider decides what is on the menu and keeps the kitchen (its inside) private. A client sends an order and gets back a result.
  2. The app is the client; the restaurant-listing service is the provider. The database sits behind the provider, hidden from the app.
  3. False. The client reaches the provider only through the API. The database is private, and the provider checks each request. If clients could read the database directly, they could damage or leak data and the provider could never change its internals.
  4. The command is curl -s "https://dummyjson.com/products/2?select=title,price". Real output at the time of writing: {"id":2,"title":"Eyeshadow Palette with Mirror","price":19.99}. (Data on a public service may change; the shape stays the same.) The id, title, and price are for product 2.
  5. Any three of: security (clients cannot touch the data directly), freedom to change the inside, one place to check and validate every request, one place to enforce rules and limits, simpler clients.
  6. As a client: a weather API and a payment API. Its own mobile app calls the hotel's own API (the one the hotel's backend team builds).
  7. Apps that read price get nothing (or crash), so they break. A careful provider keeps the old field for a while, announces the change, or publishes a new version of the API next to the old one.
  8. One possible answer: member app --API--> backend --> database and staff website --API--> backend --> database. The API sits at the backend's front door; both clients use it. The database has no direct line to either client.

Mini Challenge

Pick an app you use every day. In five lines, write: what it shows, which data you think it fetches from an API, who the provider is, and one thing about its inside that you cannot see and do not need to know. Then say what could break for you if the provider changed its API without notice.

Summary & Next Lesson

Key takeaways

  • An API is a contract: a defined way for one program to use another.
  • The client orders from the menu; the provider keeps the kitchen private.
  • Hiding the inside gives safety, freedom to change, and simplicity.
  • A web API runs over HTTP and usually answers in JSON.
  • Mobile apps, websites, other services, and scripts are all API clients.
  • A backend developer designs and runs APIs, and the design is a long-lived promise.

Next lesson

In "REST in plain language" you will learn a popular style for designing web APIs: resources named by URLs, methods as verbs, and status codes for results.

Self-check

  1. What does API stand for?
  2. In the restaurant picture, what is the menu and what is the kitchen?
  3. Why can the provider switch databases without telling clients?
  4. Name the format most web APIs use for bodies.
  5. Can one program be both a client and a provider?
Show answers
  1. Application programming interface.
  2. The menu is the API (the list of allowed requests); the kitchen is the provider's private inside (code and database).
  3. Clients only see the API, and as long as the API stays the same they cannot tell what changed behind it.
  4. JSON.
  5. Yes. A shop backend is a provider to its app and a client of a payment API.

References

  • Mozilla Developer Network, API (glossary). It defines an API as a set of features and rules that lets other software interact with a program, acting as a contract.
  • Mozilla Developer Network, REST (glossary). It notes that people call HTTP APIs "RESTful" and suggests treating them as HTTP services that standard tools can call; used for the web-API framing.
  • DummyJSON, Products documentation. It documents GET /products/{id}; the real output shown was produced by running the command.
  • The restaurant analogy and the client/provider table are this course's own teaching device. Statements that clients "cannot see the database" describe the general API design idea, not a guarantee of any specific product.

Practice

Apply this lesson with the module's lab, exercises and quiz.

Lab and exercises Quiz

Marking a lesson complete is optional and you can undo it any time. Your progress stays in this browser.

Continue to next lesson

Type to search levels, phases, modules and lessons.