Innomerc Learn
English is the default.
Web & Backend Technology

How APIs Work

Follow a client request through a service contract to data and back to a response.

Foundational6 min explorationReviewed
My learningNot started

Choose your depth. Learn at your own pace.

Simple explanation

Understand it

An application programming interface defines how software asks another component to do something. A weather app may ask a weather service for a forecast. An API describes the request and the response so the programs can work together.

Not every API is public or uses the web. This lesson uses a fictional HTTP API because it makes the boundaries visible: a client sends input, the server decides what to do, and a response returns the result.

Technical explanation

Under the hood

An HTTP API commonly combines a method, route, headers and optional request body. JSON is a common data format, but neither JSON nor HTTP alone makes an API RESTful. API contracts should specify data shapes, errors, authentication and versioning behavior.

The server validates input, authenticates when necessary, checks authorization and performs the operation. It should not trust a client’s claim that a user owns an object. Pagination, timeouts and quotas constrain how much work a request can cause.

Practitioner explanation

Practitioner perspective

Inventory who can call each route, which identities it accepts and what data or side effects it exposes. Include mobile clients, internal consumers, partner integrations and deprecated versions. An undocumented API is still an attack surface.

Observe latency, error rate, dependency calls and authorization decisions with request correlation. Changes to an API contract can break old clients even when server tests pass. Test compatibility and ensure errors do not disclose internal secrets or stack traces.

See the decision happen

Watch it work

A fictional, simplified model. Select a component to inspect it, or follow the steps in order.

Interactive Lab

Eight API communication patterns

Follow the direction and lifetime of each exchange.

Steps1. GET /orders/42 2. 200 + JSON
Click a box or choose its name to learn what it means.
ClientReadyAPI serviceReadyEvent sourceReadyClientReadyAPI serviceReadyEvent sourceReady
Ready to traceREST
Before you start · 2 stepsREST

A resource-oriented interaction; this example retrieves one representation.

How to use this example

Select Next step to read at your own pace, or Animate step to watch one exchange. Nothing advances until you choose.

Inspect components & read every step
  • Client

    A program that asks another system for information or an action.

    Example: A shopping app requests a list of products from a service.

  • API service

    A system that accepts structured requests from other software and returns results.

    Example: A weather service returns the forecast requested by an app.

  • Event source

    Something that produces a notification when a change occurs.

    Example: A new order causes an order-created event.

REST

A resource-oriented interaction; this example retrieves one representation.

  1. Client API service: GET /orders/42. The client identifies a resource using its URL.
  2. API service Client: 200 + JSON. The service returns a representation.

GraphQL

A query selects fields, but efficient backend fetching still needs implementation.

  1. Client API service: query { name }. The client submits a schema-checked field selection.
  2. API service Client: { name }. The response follows the requested selection, with errors where appropriate.

gRPC

This native gRPC example streams typed messages; browser support differs.

  1. Client API service: RPC request. A typed method call starts the stream.
  2. API service Client: Message 1. The service emits one message.
  3. API service Client: Message 2. Another ordered message arrives on this stream.
  4. API service Client: Status OK. The call ends with a status.

SOAP

XML messages carry an envelope; contracts and validation depend on the service.

  1. Client API service: XML envelope. The client sends the operation in a SOAP envelope.
  2. API service Client: SOAP response. The service returns an envelope or a SOAP Fault.

WebSocket

After establishment, both endpoints can send independently.

  1. Client API service: Connect. Establish a WebSocket connection.
  2. API service Client: Event A. The server sends without a new request.
  3. Client API service: Message B. The client sends on the same connection.
  4. API service Client: Event C. Further server messages use that connection.

Webhook

The provider calls a registered recipient; verify signatures and handle retries.

  1. Event source API service: Event. A provider-side event triggers delivery.
  2. API service Client: POST event. The provider calls the recipient’s endpoint.
  3. Client API service: 2xx ACK. The recipient acknowledges after its acceptance policy.

Server-sent events

One HTTP response carries a stream from server to browser.

  1. Client API service: GET event stream. The browser opens the event stream.
  2. API service Client: data: event 1. A server event arrives on the open response.
  3. API service Client: data: event 2. Another event arrives; this channel is one-way.

Long polling

The server holds a request until data or a timeout, then the client opens another.

  1. Client API service: GET updates. A request waits for new information.
  2. Event source API service: New data. An event makes a response available.
  3. API service Client: 200 + event. The response completes the request.
  4. Client API service: Next GET. The client opens a new waiting request.

Fictional teaching trace. One moving dot represents an exchange, not a measured network capture.

Open the detailed lesson walkthrough

Explore the system

Client

The weather app asks for the forecast for a supported location.

1 / 4

Takeaway A contract connects programs; security checks protect the boundary.

Read every step without animation

Read a forecast

  1. Client. The weather app asks for the forecast for a supported location.
  2. API contract. The server checks the request shape and allowed parameters.
  3. Service. The application obtains the forecast data.
  4. Response. The server returns a documented response and status.

A contract connects programs; security checks protect the boundary.

Attack view

A fictional client supplies an object ID belonging to another user. The API contract can be syntactically valid while the requested action is unauthorized.

Defender view

  • Validate structure and business meaning separately.
  • Authorize every object and operation on the server.
  • Limit resource use and maintain an inventory of active versions.

Common mistakes

  • An API key does not automatically identify the human user.
  • A request from your own mobile app is still untrusted input.

Check your understanding

Where should the ownership check for a requested record happen?
Active recall: explain this idea in 30 seconds

An application programming interface defines how software asks another component to do something. A weather app may ask a weather service for a forecast. An API describes the request and the response so the programs can work together.

Now give an example and name one limitation. Revisit the explanation if you get stuck.

Primary sources

Original explanations informed by these specifications and official resources. Source versions and lesson review are separate from product updates.

Content reviewed 2026-09-10. Read the editorial policy.

What comes next?

Technology fundamentals

Back to topic