APIs and JSON: How Applications Communicate

The short answer

An API is a defined interface through which one piece of software can use another. The interface states which operations are available, what input they accept, and what output or errors they can return.

An HTTP API uses HTTP to carry that exchange. JSON is one possible format for representing the data inside the request or response. They are related in many web applications, but they are not the same thing: an API is the contract; HTTP is the communication protocol; JSON is a data format.

Why applications need defined interfaces

The frontend and backend can be developed, deployed, and changed separately only if they share a dependable boundary. A product page needs to know how to ask for product 42. The backend needs to know which currency the client requested. Both sides need to agree on the shape and meaning of a successful response and an error.

Without that agreement, every call becomes a guess. A change as small as renaming price to amount can break the client even when the server, network, and database are otherwise healthy.

That agreement is an API contract. It can be written in prose, types, tests, or a machine-readable description such as OpenAPI. The OpenAPI Specification defines a standard, language-agnostic way to describe HTTP API operations and their inputs and outputs.OpenAPI describes the interface; it does not make an implementation obey the description.⁶

What an API is

API stands for application programming interface. It is the part of a system intentionally exposed for other software to use.

The interface may be remote, but it does not have to be. A browser exposes JavaScript APIs such as fetch. An operating system exposes APIs for files and processes. A library exports functions and classes. A web service may expose an API over HTTP.

The durable idea is not a particular URL or JSON object. It is a boundary with defined operations and behavior.

API versus endpoint

An API is the broader interface. An endpoint is one addressable operation or resource location within that API, depending on its design.

For an illustrative product API:

• GET /api/products/42 may retrieve one product;
• POST /api/orders may create an order;
• both endpoints belong to the same API.

An endpoint is not necessarily a physical server. A reverse proxy can route several endpoints to different services, or one application can handle all of them.

Where HTTP APIs fit

A browser frontend commonly calls a backend HTTP API. The browser's Fetch API can create a request and consume the resulting response.The WHATWG Fetch Standard defines the browser fetching model.³ HTTP supplies methods, targets, fields, content, and response status codes. The application contract gives those elements product-specific meaning.

The text equivalent is the ordered list in the diagram: frontend, HTTP request, API endpoint, HTTP response, and frontend update. A network API could instead use another protocol, and a local API might involve no network at all.

Anatomy of an API request

Consider this illustrative request target:

GET /api/products/42?currency=INR HTTP/1.1
Host: example.com
Accept: application/json

• GET is the HTTP method. It asks to retrieve a current representation.
• /api/products/42 is the path. This API uses it to identify product 42.
• currency=INR is a query parameter. The contract decides what it means.
• Accept: application/json is a request field—often called a header—stating a response format the client can accept.
• This request has no content body.

HTTP permits message content in a request independently of many method definitions, but content in a GET request has no generally defined semantics and can be rejected because of interoperability and security concerns.RFC 9110 defines GET and cautions against generating content unless the origin has directly indicated support.² In ordinary application designs, put GET inputs in the target or select another method whose semantics fit the operation.

Anatomy of an API response

The API might answer with this illustrative representation. example.com does not provide this product API; the host and data are examples.

{
  "id": 42,
  "name": "Desk Lamp",
  "price": 1499,
  "currency": "INR",
  "available": true
}

An HTTP response also has a status and fields:

HTTP/1.1 200 OK
Content-Type: application/json

200 states that the request succeeded under HTTP semantics. Content-Type tells the client how to interpret the content. The API contract explains that price is expressed in the requested currency and what available means.

What JSON is

JSON—JavaScript Object Notation—is a text format for structured data exchange. RFC 8259 defines it independently of any one programming language.RFC 8259 is the current IETF JSON standard.¹

JSON resembles JavaScript object-literal syntax, but a JSON document is text, not a live JavaScript object. A program must parse that text into values it can use. A program sending data performs the reverse transformation: it serializes values into JSON text.

JSON is common in HTTP APIs because it is compact enough for many uses and supported across languages. It is not required by HTTP, REST, or APIs in general.

Valid JSON values and syntax

JSON has six value kinds:

• object;
• array;
• string;
• number;
• true or false;
• null.

Object member names are strings and therefore use double quotes. Strings also use double quotes. Standard JSON has no comments, undefined, functions, or native date type.

{
  "name": "Desk Lamp",
  "tags": ["lighting", "home"],
  "price": 1499,
  "available": true,
  "discount": null
}

A timestamp such as "2026-09-24T10:00:00Z" is still a JSON string. The API contract—not JSON itself—says that clients should interpret it as a timestamp.

JSON numbers also do not declare an application-level integer type or universal precision guarantee. RFC 8259 explicitly allows implementations to set number range and precision limits. If an identifier or exact large number cannot safely cross all intended implementations as a number, the contract may encode it as a string.

Serialization and parsing

Serialization converts an in-memory value into a transmissible representation. Parsing reads that representation and constructs usable values.

In a browser, code might serialize a request with JSON.stringify and parse a response through response.json(). MDN's Fetch guide documents both patterns and notes that fetching does not reject merely because the server returns an HTTP error status; callers should inspect the response status.MDN demonstrates request bodies, content types, and response parsing with Fetch.⁴

Parsing answers “is this valid JSON?” It does not answer “is this acceptable order input?” A syntactically valid object may still omit a required field, contain an unsupported currency, or violate a business rule. That is why application validation remains a separate backend stage.

A complete example request and response

Here is an illustrative create operation:

POST /api/orders HTTP/1.1
Host: example.com
Content-Type: application/json
Accept: application/json

{
  "productId": 42,
  "quantity": 1
}

If the server creates the order, it might return:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/orders/9001

{
  "id": 9001,
  "status": "pending"
}

This is only an example contract. A real API must define authentication, validation rules, error shapes, idempotency expectations, and the meaning of each field. Another valid design could use different paths, methods, representations, or status codes.

REST at an appropriate high level

REST is an architectural style described by Roy Fielding, with constraints such as client-server separation, stateless interactions, cache behavior, a uniform interface, layering, and optional code-on-demand.Fielding's dissertation defines REST and explains how its constraints work together.⁵

Many teams call any JSON-over-HTTP API “REST.” That shorthand hides the distinction. An API can use HTTP methods and JSON without satisfying the REST constraints. “RESTful” is best treated as a claim about architectural choices, not a synonym for “has endpoints.”

For this learning path, the important point is narrower: HTTP gives the exchange protocol, while an API design chooses resources, operations, representations, and contracts.

APIs that do not use REST or JSON

APIs take many forms:

• GraphQL APIs commonly accept operations through a typed schema and can return JSON.
• gRPC commonly uses Protocol Buffers and HTTP/2.
• WebSocket applications can exchange messages after an HTTP-based opening handshake.
• browser, library, and operating-system APIs may be local calls rather than remote requests.

These names are not a ranking. Each represents a different interface or communication model. The lesson's API-contract idea still applies even when HTTP paths and JSON are absent.

API contracts and versioning

A useful contract makes observable behavior explicit:

• operations and addresses;
• accepted methods, fields, parameters, and content types;
• request and response shapes;
• status and error behavior;
• authentication requirements;
• compatibility expectations.

Changing a contract can break callers. Removing a field, changing its type, or giving an existing status code a new meaning may be more disruptive than adding an optional field. Versioning—whether in a path, field, media type, or release policy—is one compatibility tool, not a substitute for reasoning about consumers.

Machine-readable descriptions can help generate documentation, clients, or tests. They still need review: a schema cannot fully express every business rule, and a document can drift away from the running code.

Common misconceptions

Debugging scenario

Knowledge check

What to learn next

How a Backend Processes a Request continues from the API boundary into application execution. Authentication and Sessions then shows how later requests carry identity evidence and face permission checks.