AskELI5

computing-networking

How APIs Work

An API lets one piece of software ask another piece of software for help.

At a restaurant, you do not walk into the kitchen. You give a waiter an allowed request, the kitchen does the work, and the waiter brings a response.

  1. Two separate software programs with a request waiting between them.Client appNeeds weather dataWeather serviceKnows the forecast

    Step 1

    Two programs need to talk

    One program needs data or an action that another program knows how to provide.

  2. A restaurant waiter matched to an API carrying requests between a client and service.Restaurant waiter=API

    Step 2

    The API is the waiter

    The API defines how to ask. It separates the requesting program from the system doing the work.

  3. An API request layered into endpoint, method, details, and credentials.EndpointMethodDetailsCredentials

    Step 3

    A request follows the menu

    The client chooses an endpoint and sends the required method, details, and sometimes credentials.

  4. A request entering a server, being checked and processed, then becoming a result.Check requestDo the workPrepare result

    Step 4

    The server handles the request

    The server checks the request, runs its own logic, and prepares a result.

  5. A server response carrying a status and data back to the client application.ServerStatus + dataClient app

    Step 5

    A response comes back

    The API returns data and a status. The client decides what to show or do next.

  6. A request branching into successful, missing, forbidden, and failed API responses.SuccessRequested dataUseful statusErrorWhat failedUseful status

    Step 6

    Errors are responses too

    If the request is missing, forbidden, or impossible, the API returns a status that explains the kind of failure.

Common trap

An API is the server or database itself.

An API is the agreed interface for making requests. The server and its data stay behind that interface.

Quick check

In the restaurant analogy, which part acts like the API?

  1. The waiter
  2. The table
  3. The customer's shoes
Show the answer

The waiter carries an allowed request to the kitchen and brings the result back.

Sources

  1. Introduction to web APIsMDN Web Docs
  2. What is an API?IBM
  3. What is a REST API?Red Hat