API stands for Application Programming Interface. In the simplest words, an API is a set of rules that lets one piece of software talk to another piece of software.
Think of an API like a waiter in a restaurant. You (the customer) don’t walk into the kitchen and cook your own food. Instead, you tell the waiter what you want, the waiter takes your order to the kitchen, the kitchen prepares the food, and the waiter brings it back to you. You never need to know how the kitchen works internally — you just need to know how to order.
An API works the same way. One program (the client) sends a request, and another program (the server or a library) processes that request and sends back a response. The person using the API doesn’t need to understand the internal code — they just need to know what requests are allowed and what response to expect.
APIs exist at many levels:
- Library or framework APIs — functions you call inside your own code (for example, a Python library’s functions).
- Operating system APIs — how a program talks to the operating system to read a file or open a network connection.
- Web APIs — how applications talk to each other over the internet.
What Is a Web API?
A Web API is an API that is accessed over the internet using standard web protocols, most commonly HTTP or HTTPS. It allows a client application — like a mobile app, a website, or another server — to send a request to a remote server and get data or perform an action, without needing direct access to that server’s internal code or database.
Here is a simple example. When you open a weather app and it shows you today’s forecast, here is what happens behind the scenes:
- Your app sends a request to a weather company’s Web API (something like
https://api.weather.com/v3/forecast?city=Lahore). - The weather company’s server receives that request, looks up the forecast data, and packages it as a response — usually in JSON format.
- Your app receives that JSON response and displays it nicely on your screen.
You never see the weather company’s database or internal servers. You only interact with the API — a clean, defined “contract” that says: send me this kind of request, and I will give you back this kind of response.
Why Web APIs matter
Web APIs are the backbone of modern software because they let different systems — often built by completely different companies, in completely different programming languages — talk to each other reliably. A mobile app written in Swift can talk to a backend written in Python. A JavaScript frontend can talk to a Java backend. The API is the shared language that makes this possible.
Some everyday examples of Web APIs:
- Payment APIs (like Stripe or PayPal) that let an online store process a credit card payment.
- Social login APIs (like “Sign in with Google” or “Sign in with Facebook”).
- Maps APIs (like Google Maps) that let a food delivery app show a live map.
- Messaging APIs (like Slack’s API) that let a bot post automated messages into a channel.
Public API vs Private API
Not every API is meant for everyone. APIs are generally grouped into a few categories based on who is allowed to use them.
Public API
A public API (sometimes called an “open API”) is available for any developer to use, often after signing up for an API key. Companies release public APIs so outside developers can build tools, integrations, and apps on top of their platform.
Examples of public APIs:
- Slack’s Web API, which lets third-party developers build bots and integrations.
- Twitter/X’s API, which lets developers build apps that post tweets or read timelines.
- OpenWeatherMap’s API, which gives weather data to anyone with a free API key.
Public APIs usually come with:
- Documentation explaining every endpoint.
- Rate limits (a cap on how many requests you can send per minute or day).
- Authentication requirements (API keys, OAuth tokens, etc.).
- Terms of service that define what you are and are not allowed to do with the data.
Private API
A private API (also called an “internal API”) is built for use only within an organization. It is not published for outside developers, and it usually isn’t documented publicly at all. Private APIs let a company’s own frontend talk to its own backend, or let internal services talk to each other (a pattern common in microservices architecture).
Examples of private APIs:
- The internal API that a company’s mobile app uses to talk to its own backend servers — even though the app is public, the API itself was never meant for outside developers to use directly.
- An API used only between two internal microservices inside a company’s cloud infrastructure, never exposed to the public internet.
Partner API
There’s also a middle category worth mentioning: a partner API, which is shared only with specific, approved business partners rather than the general public. It usually requires a formal agreement and stricter access controls than a fully public API.
Why this distinction matters for security research
If you do bug bounty work or web application security testing, this distinction is important. Public APIs are expected to be probed by outside developers and are usually built with stronger authentication, input validation, and rate limiting in mind — because the company knows strangers will be sending requests to them. Private APIs, on the other hand, are often assumed to be “internal only” and may have weaker validation, since the original developers didn’t expect outside traffic to ever reach them. When a private API gets accidentally exposed to the public internet — through a misconfigured server, a leaked subdomain, or a mobile app that talks directly to backend endpoints — it often becomes a high-value target, because the assumptions that “only trusted internal systems will call this” are no longer true.
What Is an Implementation?
The word “implementation” comes up constantly in software and API discussions, so it’s worth defining clearly.
An implementation is the actual, working code that carries out a specification, design, or interface. It’s the difference between describing what something should do versus writing the real code that makes it do that.
Here’s an easy way to understand it:
- A specification (or interface, or standard) is like a blueprint. It says “here is what must happen,” without saying exactly how.
- An implementation is the actual building constructed from that blueprint.
For example:
- REST is an architectural style — a set of rules and constraints. A REST API implementation is the actual code a developer writes that follows those rules and actually responds to real HTTP requests.
- HTTP is a protocol — a defined set of rules for how messages should look. A web server (like Nginx, Apache, or a Python Flask app) is an implementation of software that understands and responds using the HTTP protocol.
- OpenAPI Specification describes what an API’s endpoints, inputs, and outputs should look like. The actual backend code that responds to those endpoints is the implementation of that specification.
You will often hear phrases like “this is just one implementation of REST” or “different frameworks have different implementations of the HTTP protocol.” This simply means: the rules stay the same, but different teams or tools can write different code that follows those same rules, sometimes with small differences in how strictly they follow them.
Understanding this distinction matters a lot in practice, because two APIs can both claim to be “RESTful,” yet behave quite differently, since REST is a style to follow — not a rigid law enforced by a compiler.
What Is a REST API?
REST stands for Representational State Transfer. It was introduced by computer scientist Roy Fielding in his year 2000 doctoral dissertation, and it has since become the most popular style for designing Web APIs.
A REST API is a Web API that follows the principles of REST. In practice, this usually means:
- Data is organized around resources (think: “users,” “orders,” “products,” “posts”) rather than around actions.
- Each resource has its own unique URL, called an endpoint (for example,
/users/42represents user number 42). - Standard HTTP methods are used to describe what you want to do with that resource:
GET— retrieve data (read a user’s profile)POST— create new data (create a new user)PUTorPATCH— update existing data (edit a user’s profile)DELETE— remove data (delete a user’s account)
- Responses are usually returned in JSON format, though XML is also technically possible.
- The API is stateless — meaning the server doesn’t remember anything about the client between requests; each request must contain all the information the server needs to process it.
A simple REST API example
Imagine a book store’s REST API. It might look like this:
| HTTP Method | Endpoint | What it does |
|---|---|---|
GET | /books | Get a list of all books |
GET | /books/101 | Get details of the book with ID 101 |
POST | /books | Add a new book |
PUT | /books/101 | Update all details of book 101 |
PATCH | /books/101 | Update part of book 101 (like just the price) |
DELETE | /books/101 | Delete book 101 |
This clean, predictable pattern is exactly why REST became so popular — once you understand the pattern, you can guess how most REST APIs work, even ones you’ve never used before.
REST API vs “RESTful” API
You will sometimes see the term “RESTful API” used interchangeably with “REST API.” Technically, “RESTful” just means an API that follows REST principles reasonably well. Very few real-world APIs implement every single constraint of REST perfectly (we’ll cover those constraints next), so “RESTful” is often used as a more relaxed, practical label.
The REST Architectural Style
REST is not a protocol, and it’s not a piece of software you install. It is an architectural style — a set of design constraints that, when followed together, produce systems with certain useful properties: scalability, simplicity, and reliability.
Roy Fielding defined six guiding constraints for REST:
1. Client-Server Architecture
The client (which asks for things) and the server (which stores and manages data) are separated. This separation means the client and server can evolve independently — you can redesign a mobile app’s interface without touching the backend, and you can upgrade backend infrastructure without breaking the app.
2. Statelessness
Each request from a client to a server must contain everything the server needs to understand and process it. The server does not store any session information about the client between requests. If authentication is needed, the client must send proof of identity (like a token) with every single request, not just the first one.
This makes REST APIs easier to scale, because any server in a cluster can handle any request — there’s no need to always route a user back to the “same” server that remembers them.
3. Cacheability
Responses must define themselves as either cacheable or non-cacheable. If a response is cacheable, the client (or something in between, like a browser or a proxy) can reuse that response for identical future requests, which reduces load on the server and speeds things up for the user.
4. Uniform Interface
This is the heart of REST. It means that resources are identified through consistent, predictable URLs, and interactions with those resources follow standard, well-known methods (the HTTP methods mentioned earlier). A uniform interface makes an API predictable and easy to learn, since once you understand the pattern for one resource, you understand the pattern for all of them.
5. Layered System
A client doesn’t necessarily know, or need to know, whether it’s talking directly to the actual server or to an intermediary — like a load balancer, a caching layer, or a security gateway. Layers can be added or changed without disrupting the overall system, as long as each layer still speaks the same interface.
6. Code on Demand (optional)
This is the only optional constraint. It allows a server to send executable code (like JavaScript) to a client, which the client can run to extend its own functionality. This one is less commonly used in typical REST API design today.
Why REST became so dominant
Before REST became mainstream, many Web APIs used a heavier, more complex style called SOAP (Simple Object Access Protocol), which relied on strict XML messaging formats and complicated tooling. REST’s simplicity — using plain HTTP methods and easy-to-read JSON — made it dramatically easier for developers to build and consume APIs quickly, which is a big reason it took over as the industry standard.
What Is the HTTP Protocol?
HTTP stands for HyperText Transfer Protocol. It is the foundational communication protocol of the World Wide Web — the set of rules that defines how a client (like a browser or an app) and a server exchange messages over a network.
Every time you type a website address into your browser, or every time an app calls a Web API, HTTP is the language being used underneath.
How an HTTP request works
An HTTP interaction always follows a request-response pattern:
- The client sends a request. This request includes:
- A method (like
GET,POST,PUT,DELETE) that describes the desired action. - A URL that identifies the resource being requested.
- Headers — extra metadata, like what content type the client accepts, or an authentication token.
- Sometimes a body — actual data being sent, such as a new user’s information in JSON format.
- A method (like
- The server processes the request and sends back a response. The response includes:
- A status code — a three-digit number telling the client what happened (explained below).
- Headers — metadata about the response, like the content type of the returned data.
- A body — the actual data returned, often in JSON format for Web APIs.
Common HTTP status codes
Status codes are grouped into categories based on their first digit:
| Range | Meaning | Common examples |
|---|---|---|
| 1xx | Informational | 100 Continue |
| 2xx | Success | 200 OK, 201 Created, 204 No Content |
| 3xx | Redirection | 301 Moved Permanently, 304 Not Modified |
| 4xx | Client error | 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests |
| 5xx | Server error | 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable |
Understanding these codes is essential — whether you’re a developer debugging why an app isn’t working, or a security researcher probing an API and noticing an unexpected 500 error that might hint at a bug worth investigating further.
HTTP vs HTTPS
HTTPS is simply HTTP wrapped inside an encrypted connection using TLS (Transport Layer Security). Without HTTPS, data sent over HTTP — like passwords, session tokens, or personal information — travels across the network in plain, readable text, meaning anyone intercepting the traffic (on public Wi-Fi, for example) could read it. Nearly all modern Web APIs require HTTPS, and browsers now actively warn users when a site only uses plain HTTP.
HTTP is stateless by design
Just like REST, HTTP itself is a stateless protocol — each request is treated as brand new, with no built-in memory of previous requests. This is exactly why REST and HTTP fit together so naturally; REST’s statelessness constraint is really just embracing HTTP’s own natural design rather than fighting against it. Any “state” you experience on a website, like staying logged in, is actually built on top of HTTP using techniques like cookies or authentication tokens sent with every request.
What Is OpenAPI Specification?
The OpenAPI Specification (often abbreviated OAS, and previously known as Swagger) is a standard, language-agnostic way to describe a REST API’s structure — its endpoints, the parameters each endpoint accepts, the format of requests and responses, authentication methods, and more — all written in a single, machine-readable document (usually in YAML or JSON format).
Think of an OpenAPI document as a detailed instruction manual for an API, but written in a format that both humans and computers can read and understand.
Why OpenAPI exists
Before OpenAPI became popular, API documentation was often written manually, in scattered wiki pages or PDFs, and it would quickly go out of date as the actual API changed. OpenAPI solves this by making the documentation part of the API’s development process itself — often generated directly from the code, or used to generate the code.
What an OpenAPI document typically contains
A basic OpenAPI file describes things like:
- Info — the API’s name, version, and description.
- Servers — the base URLs where the API can be reached (like a production server and a testing server).
- Paths — every available endpoint (like
/books/{id}) and which HTTP methods are supported on each. - Parameters — what inputs each endpoint expects (path parameters, query parameters, headers).
- Request and response bodies — the exact structure of data sent to, and received from, each endpoint (often defined using JSON Schema, which we’ll cover next).
- Security schemes — how authentication works, such as API keys, OAuth 2.0, or Bearer tokens.
What OpenAPI is used for in practice
Once an API has an OpenAPI document, that single file can power a surprising number of tools automatically:
- Interactive documentation — tools like Swagger UI or Redoc turn the OpenAPI file into a clickable, browsable web page where developers can test endpoints directly.
- Client SDK generation — tools can read an OpenAPI file and automatically generate ready-to-use code libraries in languages like Python, JavaScript, or Java, so developers don’t have to write API-calling code by hand.
- Server stub generation — some teams generate a skeleton of backend server code directly from the OpenAPI spec, then fill in the actual logic.
- API testing and validation — automated testing tools can use the OpenAPI file to check whether the real API’s responses actually match what was documented.
- Security and fuzz testing — for those of us doing security research, OpenAPI files are extremely valuable, because they map out every documented endpoint and expected input format in one place, which can guide structured testing of an API’s attack surface.
In short, OpenAPI turns an API’s documentation from a static description into a living, reusable contract that tools can actively work with.
What Is JSON Schema?
JSON Schema is a standard used to describe the exact structure, format, and rules that a piece of JSON data must follow. If JSON is the format used to send and receive data, JSON Schema is the rulebook that defines what “valid” JSON data is supposed to look like for a particular use case.
A quick note on JSON itself
JSON stands for JavaScript Object Notation. It’s a lightweight, easy-to-read format for representing structured data, built from simple building blocks: objects (key-value pairs), arrays (lists), strings, numbers, booleans, and null. It has become the default data format for most modern Web APIs because it’s simple, human-readable, and supported natively by nearly every programming language.
A simple JSON object might look like this:
{
"id": 101,
"title": "Clean Code",
"author": "Robert C. Martin",
"inStock": true,
"price": 24.99
}
What JSON Schema adds on top of JSON
JSON by itself has no built-in way to say “the id field must always be a number” or “the title field is required and must be text.” JSON Schema fills that gap. It’s essentially a JSON document that describes the rules another JSON document must follow.
Here is a simple JSON Schema for the book example above:
{
"type": "object",
"properties": {
"id": { "type": "integer" },
"title": { "type": "string" },
"author": { "type": "string" },
"inStock": { "type": "boolean" },
"price": { "type": "number", "minimum": 0 }
},
"required": ["id", "title", "author"]
}
This schema states clearly:
idmust be a whole number.titleandauthormust be text and are required fields — they cannot be missing.inStockmust betrueorfalse.pricemust be a number, and it cannot be negative.
Why JSON Schema matters
JSON Schema is used for a number of very practical purposes:
- Data validation — a server can automatically check whether incoming data (like a new user registration) matches the expected structure before processing it, rejecting malformed or unexpected input early.
- Documentation — it clearly communicates to other developers exactly what shape of data an API expects or returns, removing guesswork.
- API contracts inside OpenAPI — OpenAPI Specification documents actually use JSON Schema internally to describe the structure of request bodies and response bodies for each endpoint. This is the direct link between the two standards: OpenAPI describes the endpoints, and JSON Schema (embedded inside it) describes the data flowing through those endpoints.
- Auto-generating forms and validation code — many tools can read a JSON Schema and automatically build a matching input form, or generate validation logic in a programming language, without a developer writing that logic by hand.
- Security testing — knowing the exact expected schema of a field (its type, length limits, allowed values) helps identify where an API might accept unexpected or malformed input, which is often the starting point for testing input validation issues.
How All These Pieces Work Together
It helps to see the full picture in one place, since each concept builds on the one before it:
- HTTP is the underlying protocol — the basic rules for how any message travels between a client and a server on the web.
- A Web API is built on top of HTTP, exposing specific functionality or data to client applications over the internet.
- REST is an architectural style that shapes how that Web API is designed — organizing it around resources, standard methods, and statelessness.
- A REST API is the actual implementation — real, working code — that follows REST’s architectural style, built using HTTP as its transport protocol.
- JSON is typically the data format used to send and receive information through that REST API.
- JSON Schema defines the exact rules that each piece of JSON data flowing through the API must follow.
- OpenAPI Specification ties everything together into one master document — describing every endpoint, every HTTP method used, and every JSON Schema for requests and responses — creating a single source of truth for both humans and tools.
- Whether that API is exposed as a public API for outside developers, or kept as a private API for internal use only, depends entirely on the business’s needs and security posture.
Once you see it laid out this way, it becomes clear that none of these concepts exist in isolation — they are layers that build on top of each other to create the modern Web API ecosystem.
Common API Types Beyond REST
While REST dominates the Web API world, it’s worth knowing a few alternative styles you’ll run into:
- GraphQL — instead of many fixed endpoints, GraphQL exposes a single endpoint where the client specifies exactly what data it wants in the request itself, reducing over-fetching or under-fetching of data.
- SOAP — an older, more rigid, XML-based protocol that predates REST’s popularity, still used in some enterprise and legacy financial or government systems.
- gRPC — a high-performance API style built by Google, commonly used for fast communication between internal microservices, using a binary format called Protocol Buffers instead of JSON.
- WebSocket APIs — unlike REST’s request-response pattern, WebSockets keep a connection open so the server can continuously push data to the client in real time (useful for live chat apps or live price feeds).
API Security Basics Every Developer Should Know
Since Web APIs are one of the most common attack surfaces in modern applications, it’s worth ending with a few fundamentals:
- Always use HTTPS, never plain HTTP, to protect data in transit.
- Authenticate every request — don’t rely on the client to “remember” that a user logged in; use tokens (like JWTs or OAuth 2.0 access tokens) sent with every request, in line with REST’s stateless principle.
- Validate all input against a schema — this is exactly where JSON Schema becomes a practical security tool, not just a documentation tool, by rejecting malformed or unexpected data before it reaches business logic.
- Apply rate limiting to prevent abuse, brute-force attempts, and denial-of-service style overload.
- Never expose private/internal APIs publicly by accident — a common real-world mistake is a private API endpoint becoming reachable from the public internet due to a misconfigured server, a forgotten subdomain, or an overly permissive cloud storage bucket.
- Keep OpenAPI documentation private if it reveals sensitive internal endpoints — a leaked OpenAPI file for a private API can hand an attacker a complete map of an application’s entire backend.
Final Thoughts
Web APIs, REST, HTTP, OpenAPI, and JSON Schema are not separate, unrelated topics — they are layers of the same system, each one solving a different part of the same problem: letting software talk to other software in a predictable, reliable, and well-documented way.
If you’re just starting out, focus first on understanding HTTP and basic REST principles — everything else builds naturally on top of that foundation. If you’re already comfortable with the basics, spend time actually reading real OpenAPI documents and writing your own JSON Schemas, since hands-on practice is where these concepts really click.