Understanding REST APIs simply: from the web to SQL and JSON data

An API can be seen as an organized intermediary between two systems. Instead of reading directly from a database or from an application's code, a system sends a request to an interface designed for that purpose and receives a response in an agreed format.

In everyday life, an API can be compared to a bank counter. You go to your bank because you need information about your account: your balance, a recent transaction, or a statement. The bank already has this information in its own system. As a customer, you cannot go directly into the bank's internal databases. So you go through a counter. That counter receives your request, checks that you are authorized to access the information, and then gives you a clear and usable response.

In this analogy, the bank represents the system that holds the data, the counter represents the access point, and the bank clerk plays the role of intermediary between your request and the stored information. In an API, the principle is similar: an application does not directly access a system's tables, files, or internal processing. It sends a request to a specific address, called a URL, which can be seen as the address of the right counter. If the bank offers several counters depending on the need, you have to go to the one that provides the right information. In the same way, each API URL corresponds to a precise entry point. The API then receives the request, checks the access rules, queries the right data, and returns a structured response, often in JSON.

One important clarification is needed: a visible access point does not mean everyone can view any information. In the same way, a public API does not necessarily expose public data. It may be open to external actors while still being protected by authentication, authorization, and access-control mechanisms.

Without access control, an exposed entry point would obviously be problematic. In the case of a bank, that would mean allowing anyone to request an account history without identity verification. In software architecture, this is exactly why a serious API frames data access with clear security rules.

Modern systems almost never live in isolation. A website needs to retrieve products, a customer portal must display invoices, an audit tool must read financial data, a CRM must interact with an ERP, and a mobile application must synchronize information with a remote server.

Without APIs, each system would have to access the internal data of other systems directly, which would be fragile, risky, and difficult to maintain. The API makes it possible to control what is exposed, in what format, with which security rules, and for which uses.

In other words, the API avoids giving everyone the keys to the house. It only opens the right door, at the right time, according to known rules. In a business context, that allows an ERP, a reporting portal, or a platform like IBM Planning Analytics to retrieve useful data without directly exposing the entire underlying technical structure. The user sees clear information in the interface, while the API takes care of fetching the right data from the right place.

When people talk about web APIs today, they very often mean REST APIs. This generally means an application exposes resources through URLs and we interact with them using the standard mechanisms of the web, especially HTTP.

In simple language, a REST API organizes exchanges around identifiable resources, such as customers, orders, invoices, or products. Each resource has an address, and an explicit method is used to indicate the intended action.

In practice, many teams say REST even when their API is not strictly RESTful in the academic sense. That is not a problem for learning. To get started, it is enough to remember that a REST API is a web API structured around resources, clear URLs, and standard methods.

The URL is the address to which a request is sent. It often contains several parts: the protocol, the domain, a path, and sometimes parameters.

Using the bank counter image again, the URL is not the clerk, but the address of the right counter. It tells you which service should receive the request.

Let's take a simple example: https://api.example.com/customers/42?include=orders

- The protocol is https.

- The domain is api.example.com.

- The path /customers/42 refers here to a specific resource, for example customer number 42.

- The include=orders parameter indicates that the response should optionally be enriched with that customer's orders.

A good URL should be readable, stable, and resource-oriented. You request an identifiable resource. You do not write a vague sentence. The URL is not there to tell a story; it is there to point to a specific piece of information or action.

A REST API generally relies on HTTP methods to express the intent of the request. This is fundamental. The URL says what you are targeting. The method says what you want to do.

GET is used to read. POST is used to create. PUT is often used to replace an existing resource. PATCH is used to partially modify a resource. DELETE is used to remove one. Other methods exist, but these cover the essentials for most business uses.

When learning APIs, we should stop seeing these words as unnecessary technical vocabulary. They are simply standardized verbs used to manipulate resources on the web.

A good way to teach APIs to non-technical profiles is to read each call like a structured sentence.

For example, GET /invoices/125 means: I want to read invoice number 125. POST /customers means: I want to create a new customer. PATCH /customers/42 means: I want to modify part of customer 42's information.

This reading is simple, healthy, and pedagogical. It helps show that an API is not mysterious. It simply expresses an intention on a resource through a shared convention.

An API response generally contains several elements: a status code, sometimes technical headers, and very often a structured content block called the body.

The body is often in JSON. It has become the dominant format for web API exchanges because it is both readable for humans and easy for applications to interpret.

A response may return a single object, a list of objects, an error message, pagination metadata, or a success indicator.

HTTP status codes quickly indicate whether the request succeeded or not. They are very useful for reading the result of an exchange without inspecting everything in detail.

A 200 code generally means the read succeeded. A 201 means a creation was completed. A 400 often signals an invalid request. A 401 means the user is not authenticated. A 403 means the user does not have permission. A 404 indicates the resource was not found. A 500 indicates a server-side error.

For a business, audit, or data profile, these codes can be seen as diagnostic signals. They help determine whether the problem comes from the request, the permissions, the resource itself, or the target system.

In our banking analogy, we should avoid a common confusion: a counter visible from the outside does not mean everyone can obtain any information. It can be open to the public while still requiring identity verification and precisely limiting what is accessible.

In the same way, a public API does not necessarily expose public data. It mainly refers to an API that is accessible to actors outside the system, such as partners, customers, or third-party developers. That API can still be strongly protected by authentication, authorization, quotas, and access-control mechanisms.

Conversely, a private API is generally reserved for internal exchanges between applications within the same organization. Technically, it may look similar to a public API, but its exposure, governance, and uses are different.

This distinction matters for architecture, security, and audit topics. An API is not only a data-exchange format. It is also an exposure surface that must be governed rigorously.

Consuming an API means sending a request and then using the response. This can be done by a web application, a mobile app, an automation script, an ETL, a BI tool, or a technical connector.

In a front-end application, we often send an HTTP request and then transform the JSON response to display it in a table, a customer record, a dashboard, or a form.

The key point to understand is this: consuming an API does not only mean calling a URL. It means managing a complete conversation with a remote system: success, errors, loading states, missing data, permissions, formats, and possible schema differences.

For profiles familiar with SQL, an API often becomes much clearer as soon as we make a direct comparison with a read query on a table.

In SQL, you query a relational structure directly. In an API, you ask an interface to expose a controlled view of the data. The business logic, access rules, transformations, and return format may all be handled by the API.

In other words, SQL speaks directly to the data engine. The API speaks to a service layer that can then query one or more databases, reformat the data, and apply security rules.

The SQL parallel is useful, but the two should not be confused. An API is not just another syntax for writing SQL.

The API can hide the real database structure, aggregate multiple sources, restrict certain fields, rename data, enrich the response, log accesses, and enforce business validations.

In many organizations, that role is precisely what makes APIs essential: they create a contractual layer between consumers and internal data.

JSON became dominant because it is easy to read, lightweight to transmit, and very natural for representing objects, lists, and nested structures.

Where SQL often returns a tabular logic made of rows and columns, JSON makes it possible to represent complete business objects more directly, sometimes with nested sub-objects or associated lists.

For example, a customer can be returned with an address, preferences, and recent orders in a single structured response. This ability to represent hierarchical structures is especially useful for modern web applications.

JSON is not the same thing as NoSQL. This is a very common confusion. JSON is first and foremost a data representation or exchange format.

An API can absolutely return JSON while its data is stored in a relational SQL database. Conversely, a document-oriented NoSQL database can store JSON-like structures, but that belongs to the persistence model, not just the response format.

So we need to distinguish three things: how data is stored, how data is queried, and the format in which data is exchanged.

Imagine a customers table and an orders table. In SQL, we might run several queries or a join to reconstruct the view of a customer with their orders.

In an API, it is common to receive a response that is more directly usable by the application, in the form of an enriched business object.

This difference explains why front-end, mobile, or integration teams often like working with well-designed APIs: they expose data in a shape that is already close to the actual usage need.

A good API should inspire clarity. URLs should be understandable. Methods should be consistent. Responses should be structured. Errors should be readable. Security rules should be explicit.

A bad API, by contrast, mixes conventions, exposes inconsistent names, returns opaque errors, changes schema too often, or forces consumers to guess what must be sent.

For a company, API quality is not a technical luxury. It is a direct factor in maintainability, integration, reliability, and cross-team understanding.

The right method is to progress in three steps. First, understand the general idea: an API is a controlled access door to a resource. Then learn the minimum conventions: URL, method, request, response, status. Finally, connect that to concrete use cases: reading customers, creating invoices, comparing with SQL, reading JSON, and handling errors.

Many people get stuck because they start too early with authentication details, complex headers, or frameworks. The conceptual logic must come first.

Once that foundation is understood, the rest becomes much simpler: API documentation, tools like Postman, front-end consumption, back-end integration, security, and versioning.

Understanding an API does not mean learning some magic reserved for developers. It means understanding how systems talk to each other in a controlled, readable, and standardized way.

REST, HTTP, CRUD, URLs, response statuses, and JSON are not separate ideas. They all describe the same exchange mechanism from complementary angles.

For a business, finance, audit, or data profile, the comparison with SQL is often the best entry point. SQL helps explain the logic of reading and manipulating data. The API adds the service, security, formatting, and exposure layer. And JSON makes it possible to exchange that data in a simple, flexible form suited to modern applications.