The Project | About Us | Contribute | Donations | License

HOME

Knowing the history of APIs is not an exercise in nostalgia: it is the quickest way to understand why REST is the way it is. Every decision that seems obvious today — using HTTP, returning JSON, identifying resources with addresses — was the answer to a specific problem that earlier technologies failed to solve. This lesson traces that path from the remote procedure calls of the 1980s to today's ecosystem of API-first, gateways and microservices, and ends by drawing out the practical lessons that are useful to anyone designing an API today, Aroma Store included.

The starting point: calling code that lives on another machine
RPC, CORBA and DCOM: the era of tight coupling
The web and HTTP as a universal substrate
XML-RPC, SOAP and the WS-* stack
Roy Fielding and the birth of REST (2000)
The rise of public APIs and the API economy
From XML to JSON
Mobile as an accelerator
The current era: API-first, OpenAPI, gateways and microservices
GraphQL and gRPC: answers to specific limits of REST
What lessons this history leaves (and why Aroma Store chooses REST)

The starting point: calling code that lives on another machine

For decades, a program was a single piece running on a single computer. When networks appeared, an obvious need emerged: for a program to be able to use functions that live on another machine. And with it came the question that has guided 40 years of technology:

How do I make calling something remote resemble calling a local function as closely as possible?

That question, phrased that way, turned out to be a trap. A local call is instantaneous, reliable and does not fail for reasons outside the program. A remote call takes milliseconds or seconds, may be lost, may arrive twice and may wait forever. The eight famous "fallacies of distributed computing" (the network is reliable, latency is zero, bandwidth is infinite, the network is secure...) describe exactly which assumptions break down. A good part of the history that follows consists of learning this lesson over and over again.

RPC, CORBA and DCOM: the era of tight coupling

The first answer was RPC (Remote Procedure Call), popularised by Sun in the 1980s. The idea: the developer writes getCoffee(1) and an intermediate layer (the stub) packages the call, sends it over the network, unpacks it on the server, runs the real function and returns the result.

The 1990s brought more ambitious, object-oriented versions:

CORBA (Common Object Request Broker Architecture), from the OMG consortium: cross-platform and cross-language, with an interface definition language (IDL) and a broker (ORB).
DCOM, Microsoft's proposal, integrated into the Windows world.
RMI, the Java-specific proposal.

They worked, and in controlled environments they worked well. But they accumulated serious problems:

Problem	Practical consequence
Tight coupling between client and server	Changing an interface meant regenerating and redeploying every client at once
Proprietary binary protocols	Firewalls blocked them; crossing the internet was a nightmare
Platform or vendor lock-in	DCOM tied you to Windows; CORBA ORBs from different vendors did not always understand each other
State on the server	References to live remote objects were kept, which made scaling and surviving crashes harder
Complexity	A steep learning curve and heavyweight tooling
The illusion of transparency	Because calls looked local, people wrote code that made hundreds of remote calls without realising it

The lesson that stuck: hiding the network does not remove it. A remote design must explicitly acknowledge that latency and failures exist.

The web and HTTP as a universal substrate

Meanwhile, in parallel, something apparently unrelated was happening: Tim Berners-Lee was inventing the World Wide Web (1989-1991) with three pieces — URL, HTTP and HTML — intended for sharing documents between scientists.

The web had properties that enterprise distributed systems lacked:

A universal namespace: anything could be identified with a URL.
A simple, textual protocol that crossed firewalls because everybody let port 80 through.
Stateless, which allowed it to scale to millions of users and to add intermediate caches.
Language and platform independent: all you needed was to speak text over a socket.

By the end of the 1990s the conclusion had become hard to ignore: the web had scaled to planetary size with a far simpler model than CORBA. What if, instead of inventing a new transport, you used the one that already worked?

XML-RPC, SOAP and the WS-* stack

The first answer to that question was, curiously, to do RPC again but on top of HTTP and with XML. In 1998 XML-RPC appeared: procedure calls serialised in XML and sent by POST. Simple and readable.

From there evolved SOAP (Simple Object Access Protocol), driven by Microsoft and IBM and later standardised by the W3C, and with it the whole "web services" family: WSDL to describe the contract in a machine-readable way, UDDI to discover services and the WS-* stack (WS-Security, WS-ReliableMessaging, WS-AtomicTransaction) to add security, reliability and transactions.

SOAP solved real problems: a formal, verifiable contract, automatic client code generation, message-level security and transport neutrality. But the stack grew so much that it became heavy: verbose XML messages, enormous specifications, total dependence on tooling and an implementation that was hard without an IDE to generate everything. We will compare both approaches in detail in lesson 01-06.

The important consequence for our story is that SOAP used HTTP as a mere tunnel: everything went by POST to a single endpoint, ignoring the protocol's methods, status codes and caching. Someone was bound to point out that this was wasting the web.

Roy Fielding and the birth of REST (2000)

In 2000, Roy Fielding — co-author of the HTTP/1.1 specification — published his doctoral thesis Architectural Styles and the Design of Network-based Software Architectures. Its chapter 5 describes REST (Representational State Transfer).

What matters about the thesis is its method: Fielding did not invent a technology, he described why the web worked. He analysed the desirable properties of an internet-scale distributed system (scalability, independent evolution, visibility, portability) and derived a set of architectural constraints that produce them: client-server, stateless, cache, uniform interface, layered system and code on demand.

Two nuances that are constantly misinterpreted and that are worth pinning down right now:

REST is not a protocol or a standard: it is an architectural style. There is no "REST" specification to validate against.
REST does not mean "JSON over HTTP". Many APIs called REST fail to meet several of its constraints.

We will develop the constraints one by one in lesson 01-04, and in 01-05 we will see a tool for measuring how close a real API comes to the model.

For the first few years, REST was an academic idea with few followers. What made it dominant was what happened in parallel in the commercial world.

The rise of public APIs and the API economy

In the early 2000s, several companies discovered that exposing their services to third parties multiplied their reach:

Year	Milestone	Why it mattered
2000	Salesforce launches its XML API	The first major company born with the API as part of the product
2000	eBay opens its API	Lets external tools list and manage auctions
2002	Amazon opens its commerce API	Affiliates sell Amazon products from their own websites
2004	Flickr publishes its API	The engine of mashups: combining services from several providers
2006	Amazon Web Services (S3, EC2)	Infrastructure itself becomes something consumed via API
2006	Twitter and Facebook open their APIs	Entire ecosystems of third-party applications

One telling episode: when Amazon offered both styles, the vast majority of developer traffic ended up using the REST variant rather than the SOAP one, simply because it could be tried out in a browser and required no special tooling. Simplicity won by adoption, not by decree.

From this comes the phrase "API economy": the API stops being a technical detail and becomes a business channel. The so-called "Bezos mandate" (2002) also became well known — Amazon's internal directive that every team had to expose its data and functionality exclusively through service interfaces, no exceptions. That principle — communicating only through well-defined interfaces — is the cultural seed of microservices.

For Aroma Store this translates into something very concrete: publishing its catalogue via an API is not just a technical whim, it is what allows comparison sites and coffee blogs to generate traffic and sales.

From XML to JSON

At first, almost every API returned XML. Let's compare the same information in both formats.

In XML, as it looked in 2004:

<?xml version="1.0" encoding="UTF-8"?>
<coffee>
  <id>cof_001</id>
  <name>Ethiopia Yirgacheffe</name>
  <origin>Ethiopia</origin>
  <roast>light</roast>
  <priceEuros>14.50</priceEuros>
  <stock>120</stock>
</coffee>

In JSON, as we return it today:

{
  "id": "cof_001",
  "name": "Ethiopia Yirgacheffe",
  "origin": "Ethiopia",
  "roast": "light",
  "priceEuros": 14.50,
  "stock": 120
}

The second takes up roughly half the space and, above all, in a browser it is already a usable object:

// Consuming JSON from the browser: two lines and no extra parser.
const response = await fetch('https://api.aromastore.example/v1/coffees/cof_001');
const coffee = await response.json();   // JSON -> JavaScript object
console.log(coffee.priceEuros);         // 14.5

// With XML you would have had to walk a DOM tree:
// document.getElementsByTagName('priceEuros')[0].textContent -> "14.50" (text, not a number)

JSON was formalised by Douglas Crockford from 2001 onwards and later standardised (ECMA-404, RFC 8259). It prevailed because:

It is more compact, which matters on mobile networks.
It maps naturally onto the data types of modern languages.
It is easier to read for a human who is debugging.
It does not need XML's heavy apparatus of schemas and namespaces (although JSON Schema exists for when validation is needed, as we will see in 03-04).

XML did not disappear: it is still alive wherever strict validation, digital signatures or mixed documents are requirements, and in many financial and healthcare systems.

Mobile as an accelerator

The arrival of the iPhone (2007) and the App Store (2008) changed priorities overnight. Mobile applications needed a backend, and that backend was a web API. This shift imposed constraints that pushed even harder towards REST + JSON:

Limited and expensive bandwidth: every byte counts, and XML was heavy.
High latency: minimising the number of round trips becomes critical. This is where the criticism of over-fetching that motivates GraphQL would later be born.
Battery: less radio time, less consumption.
Multiple clients on the same API: web, iOS and Android sharing a backend.
Eternal old versions: the user decides when to update the app, so the API must keep serving clients from two years ago. This point, more than any other, turned versioning (lesson 02-07) into a compulsory discipline.

The current era: API-first, OpenAPI, gateways and microservices

During the 2010s the ecosystem matured and four ideas appeared that we now take for granted:

API-first: the API is designed before it is implemented, reviewed with its consumers and agreed as a contract. The code comes afterwards. It is the opposite of "we expose whatever comes out of the data model".
OpenAPI (formerly Swagger): a standard format for describing a REST API in a machine-readable way. From that description come browsable documentation, generated clients, mock servers and automated tests. It is, in a sense, the WSDL that REST never had, but optional and far lighter. We will work with it in 05-02.
API gateways and developer portals: a layer in front of the API that centralises authentication, usage limits, metrics and routing, plus a portal where consumers register and obtain credentials (lesson 05-06).
Microservices: breaking a large application into small services that communicate via APIs. It multiplied the number of APIs in a company: not just the public ones, but dozens of internal ones.

GraphQL and gRPC: answers to specific limits of REST

By the middle of the decade it was clear that REST, excellent though it is, did not solve everything equally well. Two alternatives appeared, each attacking a different limitation:

GraphQL (Facebook, 2015): born from the mobile problem of requesting tailored data. In a REST API, rendering an order screen may require three or four requests, and each one returns more fields than needed. GraphQL lets the client ask for exactly the fields it wants in a single query.
gRPC (Google, 2015): it is RPC again, but done properly for the modern era: an explicit contract in a .proto file, compact binary serialisation with Protocol Buffers, HTTP/2 and streaming. Its natural territory is communication between internal services, where performance matters more than being reachable from a browser.

It is interesting to note that gRPC closes the circle: we are back to RPC, but with the lessons learned (explicit contract, standard transport, no illusion of transparency). We will compare both with REST, alongside webhooks, in lesson 01-07.

graph LR
    A["1980s<br/>RPC<br/><i>remote calls</i>"] --> B["1990s<br/>CORBA · DCOM · RMI<br/><i>tight coupling</i>"]
    B --> C["1991-1998<br/>Web + XML-RPC<br/><i>HTTP as substrate</i>"]
    C --> D["1999-2005<br/>SOAP and WS-*<br/><i>contract and heavy stack</i>"]
    D --> E["2000<br/>REST (Fielding)<br/><i>architectural style</i>"]
    E --> F["2000-2008<br/>Public APIs + JSON<br/><i>the API economy</i>"]
    F --> G["2008-2015<br/>Mobile and OpenAPI<br/><i>lightweight contract</i>"]
    G --> H["2015-today<br/>GraphQL · gRPC · events<br/><i>API-first and microservices</i>"]

What lessons this history leaves (and why Aroma Store chooses REST)

Five lessons applicable to any API you design today can be drawn from the whole journey:

Interoperability beats elegance. The technologies that succeeded were the ones that worked from any language, platform and network, even when technically more sophisticated options existed.
Simplicity gets adopted; complexity gets abandoned. SOAP was more complete than REST and lost share on the public web. If a developer can try your API with curl in thirty seconds, they will use it.
The network cannot be hidden. Every attempt to pretend that a remote call is local ends badly. Design assuming latency, failures and retries.
Every API must be able to evolve. The ones that survive are those that can add things without breaking existing clients. CORBA's tight coupling was its downfall.
There is no single right answer. Technologies coexist: today it is normal to have REST facing outwards, gRPC between services and events for anything asynchronous.

Aroma Store's decision in 2026

With this context, the Aroma Store team's choice speaks for itself:

Need	Decision	Historical reason
Public catalogue API for blogs and comparison sites	REST + JSON	Maximum interoperability and a minimal barrier to entry; it can be tried from the browser
Web, mobile app and internal panel on the same backend	Versioned REST	A stable contract that outlives old mobile apps
Taking advantage of caches and standard infrastructure	REST over HTTP	Methods, codes and caching native to the protocol, with nothing to invent
Communication between its own internal services	gRPC (we will see it in 01-07)	Performance and a strong contract where you control both ends
Notifying SwiftShip about a paid order	Webhooks	The notification must go out from the server, not wait for someone to ask

Common Mistakes and Tips

Believing that REST "replaced" SOAP everywhere. SOAP is still alive in banking, insurance and healthcare. You will see REST façades built on top of legacy SOAP services for many years to come.
Reading GraphQL or gRPC as "the next version of REST". They are not successors, they are tools for different problems. Choosing on novelty is the worst of reasons.
Repeating CORBA's mistake under modern names. If your internal API forces client and server to be deployed together, you have reintroduced tight coupling, whatever technology you use.
Designing the API from the data model. The API-first approach exists precisely because exposing your tables produces contracts that are impossible to maintain.
Tip: when someone proposes an integration technology to you, ask what specific problem it solves in your context. This whole history is a succession of solutions that were excellent for their problem and disastrous outside it.

Exercises

Exercise 1: from problem to technology

Match each historical problem with the solution that addressed it and explain the link in one sentence:

Problems: (a) binary protocols do not cross firewalls; (b) XML is too heavy for mobile networks; (c) there is no automatic way to generate clients for a REST API; (d) the mobile client needs four requests to render one screen.

Solutions: OpenAPI, JSON, GraphQL, HTTP as the transport.

Exercise 2: justify an architectural decision

Aroma Store wants its roasting supplier (an external company, with old Windows-based systems) to receive production orders automatically. A colleague proposes exposing remote objects with DCOM because "that way they call our methods directly". Write a reasoned reply with three historical arguments against it and an alternative proposal.

Exercise 3: translate XML to JSON with judgement

This is the fragment returned by a legacy Aroma Store system. Convert it into a modern JSON response, applying what you have learned in this lesson and the previous one (clear names, explicit units, correct types, appropriate wrapper).

<orders>
  <order num="5001" customer="842">
    <date>14/07/2026</date>
    <amount>29.40</amount>
    <status>P</status>
  </order>
</orders>

Solutions

Solution 1

(a) HTTP as the transport: by travelling over port 80/443 in text form, requests cross firewalls and proxies that used to block CORBA and DCOM.
(b) JSON: a far more compact format that is directly usable by the client, key during the mobile explosion.
(c) OpenAPI: it describes the API in a machine-readable way, making it possible to generate documentation, clients and mocks — which was the main advantage SOAP had with WSDL.
(d) GraphQL: it allows exactly the fields of several resources to be requested in a single query, attacking both under-fetching and over-fetching.

Solution 2

Three historical arguments:

Tight coupling: with remote objects, any interface change forces you to coordinate deployments with an external company you do not control. It is exactly the flaw that sank CORBA and DCOM.
Crossing the network: DCOM uses dynamic ports and binary protocols that corporate firewalls block; integrating two companies over the internet on that basis is a permanent source of incidents.
Platform and vendor lock-in: DCOM ties both parties to Windows forever and limits Aroma Store's future technology options.

Alternative: expose a partner REST API with authentication using the supplier's credentials and, for real-time notification, a webhook that notifies the supplier when there is a new production order. If the supplier cannot receive webhooks (old systems often cannot), offer them the option of periodically polling a pending-orders resource.

Solution 3

{
  "data": [
    {
      "id": "ord_5001",
      "customerId": "cus_842",
      "createdAt": "2026-07-14",
      "totalEuros": 29.40,
      "status": "paid"
    }
  ],
  "total": 1
}

Improvements applied:

The date moves to ISO 8601 format (2026-07-14), unambiguous compared with 14/07/2026.
amount becomes totalEuros, with the unit made explicit in the name.
The cryptic code P becomes a readable value from a closed set (paid); an external consumer has no reason to know your internal code table.
Identifiers carry a prefix (ord_, cus_) and are strings, not numbers, which avoids losing leading zeros and makes it easier to change the scheme.
The list is wrapped in data with a total, leaving room for pagination metadata (lesson 02-06).

Conclusion

The history of APIs is the history of a single problem — getting two systems to understand each other — solved successively with RPC, distributed objects, SOAP web services and, finally, REST over HTTP with JSON. Each stage left a lesson: the network cannot be hidden, tight coupling is paid for dearly, interoperability and simplicity are what determine adoption, and every API must be able to evolve without breaking its consumers. Today REST, GraphQL, gRPC and event-based communication coexist, and Aroma Store will combine them as the case demands: REST facing outwards, gRPC facing inwards and webhooks for integrations.

Before studying REST proper, we need to master the ground it stands on. In the next lesson, HTTP Fundamentals for APIs, we will open the protocol right up: the exact anatomy of a request and a response, what it means for HTTP to be stateless, the parts of a URL, the most common headers and why every API must travel encrypted.

History and Evolution of APIs

Contents