Introduction to APIs & Web Services
Before you can test an API, you need to feel in your bones what one is — not as a definition to memorise, but as a thing you can picture. APIs are the invisible plumbing behind almost every app you use: when you check the weather, pay for coffee, or watch a map load, software is quietly talking to other software. This module builds that mental picture from the ground up, then shows you why testing APIs directly makes you faster, earlier and far more valuable than someone who only clicks buttons on a screen.
Learning objectives
By the end of this lesson you will be able to:
- Explain in plain language what an API is, using everyday analogies that stick.
- Describe the client–server model and where a web service fits into it.
- Tell the difference between REST and SOAP, and say why REST dominates modern APIs.
- Define the core vocabulary: endpoint, resource, request, response, and JSON.
- Explain why testers test APIs directly — faster, earlier and more stable than UI testing — and where API tests sit in the test pyramid.
- Read and reason about a simple first API request from start to finish.
What is an API? Introduction to APIs the easy way
API stands for Application Programming Interface. Ignore the jargon for a moment. An API is simply a way for one piece of software to ask another piece of software to do something or give it some data, using a set of agreed rules. It is a contract: “If you ask me in exactly this way, I promise to answer in exactly that way.”
Three analogies that make it click
The restaurant waiter. You sit at a table and want food from the kitchen, but you never walk into the kitchen yourself. You tell the waiter what you want from the menu; the waiter carries your order to the kitchen and brings back the dish. The API is the waiter: the messenger that takes your request to the system and brings back the response. The menu is the list of things you are allowed to ask for.
The electrical socket. You do not rewire your house to charge your phone — you plug into a standard socket. The socket is an interface: as long as your plug matches the agreed shape, you get power without knowing anything about the power station. An API is that standard socket for software.
The ATM. You press buttons on a cash machine to withdraw money. You never see the bank’s database or its security systems — you just use a small, well-defined set of operations (check balance, withdraw, deposit). The ATM screen is an interface to the bank. An API is the same idea, but software-to-software instead of human-to-machine.
The crucial insight in every analogy is hiding complexity. The kitchen, the power station, the bank’s database — all hidden. You only deal with a small, predictable set of requests and responses. That is what an API gives developers: a simple, stable way to use something complicated without needing to understand its insides.
The client–server model
Almost every API conversation has two roles:
- Client
- The one doing the asking. A client might be a web browser, a mobile app, a smart TV, another server, or — for us — a testing tool like Postman or an automated test script. The client sends a request.
- Server
- The one doing the answering. The server holds the data and the business logic. It receives the request, does the work, and sends back exactly one response.
The whole dance is: client sends a request → server does work → server returns a response. That is it. A single app can be both: your food-delivery app is a client when it asks the restaurant service for menus, and that restaurant service might itself be a client when it asks a payments service to charge your card. Modern systems are layers of services talking to services, and each conversation is a request and a response.
What is a web service?
A web service is simply an API that is available over a network, usually the internet, using web technologies (mainly HTTP, which you will study in depth in the next module). Every web service is an API, but not every API is a web service — some APIs live entirely inside a single program. In this course, when we say “API” we almost always mean a web service: something you can reach at a web address and call across a network.
Because web services travel over HTTP, they have a home address — a URL — just like a website. The difference is that a website returns a pretty page for humans to read, while a web service usually returns raw data for other software to use. Same plumbing, different audience.
REST vs SOAP — and why REST won
There are different styles for building web services. The two you will hear about are SOAP and REST.
| Aspect | SOAP | REST |
|---|---|---|
| What it is | A strict protocol with rigid rules | An architectural style with flexible conventions |
| Data format | XML only, wrapped in a SOAP “envelope” | Usually JSON (also XML, text, etc.) |
| Verbosity | Heavy, lots of boilerplate | Lightweight and readable |
| Uses HTTP verbs? | Mostly just POST | Yes — GET, POST, PUT, PATCH, DELETE map to actions |
| Where you see it | Older enterprise, banking, telecom systems | The vast majority of modern web and mobile APIs |
REST (Representational State Transfer) dominates today because it is simple, readable, and rides on the plain mechanics of the web. It treats everything as a resource with a web address, and uses ordinary HTTP methods to act on those resources. A quick comparison: to get customer 42, a SOAP service might need a chunk of XML inside an envelope posted to a single endpoint, while a REST service just uses GET /customers/42. The REST version reads almost like a sentence. That clarity, plus JSON being lighter than XML, is why REST became the default. SOAP still exists — especially in finance and legacy enterprise systems — so it is worth recognising, but this course focuses on REST because that is what you will test 95% of the time.
The core vocabulary: endpoints, resources and JSON
A handful of words appear constantly. Lock them in now.
- Resource
- A “thing” the API lets you work with — a user, an order, a product, a post. Resources are usually plural nouns in the URL:
/users,/orders,/products. - Endpoint
- The full web address where you reach a resource or action. For example
https://api.example.com/users/42is an endpoint that points at user 42. The combination of an endpoint and an HTTP method (likeGET) defines one operation. - Request
- What the client sends: a method, a URL, some headers, and sometimes a body of data.
- Response
- What the server sends back: a status code, headers, and usually a body of data.
- JSON
- JavaScript Object Notation — the lightweight text format most APIs use to send data. It is just keys and values that both humans and machines can read.
Here is a tiny slice of JSON describing a user. Notice it is only text — curly braces for an object, keys in quotes, values after a colon, items separated by commas:
{
"id": 42,
"name": "Asha Rao",
"email": "asha@example.com",
"isActive": true,
"roles": ["reader", "editor"]
}JSON values can be strings ("Asha Rao"), numbers (42), booleans (true/false), null, arrays (the square-bracketed list of roles), or nested objects. That is the entire grammar — you can learn to read JSON in an afternoon, and you will read a lot of it as an API tester.
Why testers test APIs directly
You might wonder: if the app already has a screen, why not just test through the screen? Because testing the API directly is faster, earlier and more stable than testing only through the user interface. This is one of the most important ideas in the whole course.
- Faster
- A UI test has to launch a browser, load pages, wait for images and scripts, and click through screens — seconds per step. An API test sends a request and reads a response in milliseconds. You can run thousands of API checks in the time one UI journey takes.
- Earlier
- The backend is usually built before the polished screens. If you can test the API, you can find bugs weeks earlier — before the UI even exists. Finding a defect early is dramatically cheaper to fix than finding it after release.
- More stable
- UI tests are famously flaky: a moved button, a renamed label, or a slow animation breaks them. APIs change their contract far less often, so API tests fail because something is genuinely broken, not because a pixel moved.
- More thorough
- Many conditions are hard or impossible to trigger from the UI — sending malformed data, missing fields, invalid tokens, or hitting rate limits. At the API level you can send anything and check how the system defends itself.
A day-in-the-life example
Imagine a signup form. Through the UI you can test a handful of journeys before you lose patience. At the API level you can fire POST /register with: a valid user, a duplicate email, a missing password, a 500-character name, an email with no @, SQL-looking text in a field, and an empty body — dozens of cases in under a minute, each with a precise assertion on the status code and message. The same coverage through the UI would take a morning and break the next time a designer tweaks the form.
Where API tests sit in the test pyramid
The test pyramid is a simple picture of how to balance your testing effort. It has three layers:
| Layer | What it tests | Speed & cost | How many |
|---|---|---|---|
| UI / End-to-end (top) | The whole app through the screen | Slow, expensive, flaky | Few |
| API / Service (middle) | Business logic through the API, no UI | Fast, stable, cheap | Many |
| Unit (bottom) | Individual functions in code | Fastest, cheapest | Most |
The pyramid is wide at the bottom and narrow at the top: lots of tiny unit tests, a solid layer of API tests in the middle, and only a few slow end-to-end UI tests on top to confirm the whole thing hangs together. As a tester, the API layer is your sweet spot — it gives you the most coverage for the least cost and flakiness. A common anti-pattern is the “ice-cream cone”: a huge pile of brittle UI tests and almost no API tests. Learning API testing is how you help your team turn the cone back into a pyramid.
Going deeper: APIs you already rely on
APIs are everywhere, often invisibly. A weather widget calls a weather API. A “Pay with card” button calls a payments API like Stripe. “Sign in with Google” uses Google’s identity API. A shop’s map calls the Google Maps API. A travel site shows flights by calling many airline APIs at once and merging the results. For practising, several free public APIs exist specifically so learners can send real requests: JSONPlaceholder (fake posts and users), ReqRes (fake user data with real responses), and httpbin.org (echoes your request back so you can see exactly what you sent). We will use these throughout the course.
Your first request, walked through
Let us read one complete, simple request and response so nothing feels mysterious. Suppose we ask JSONPlaceholder for the post with id 1. The request — which you could type in a browser, Postman, or the command line — is just:
GET https://jsonplaceholder.typicode.com/posts/1As a curl command (a tiny tool for sending HTTP requests from the terminal) it looks like this:
curl https://jsonplaceholder.typicode.com/posts/1Breaking the URL apart: https:// is the protocol, jsonplaceholder.typicode.com is the server’s address, /posts is the resource (all posts), and /1 is the specific post we want. The method is GET because we are reading data, not changing it. The server answers with a status code and a JSON body:
HTTP/1.1 200 OK
Content-Type: application/json
{
"userId": 1,
"id": 1,
"title": "sunt aut facere repellat provident",
"body": "quia et suscipit suscipit recusandae..."
}Read it top to bottom like a tester: the status is 200 OK (success), the Content-Type confirms it is JSON, and the body contains a post whose id is 1 — exactly what we asked for. That final check matters: a success status with the wrong post would still be a bug. Every one of those observations is a potential assertion, which is precisely what you will automate in Postman starting in Module 3.
Common misunderstandings to avoid
- “An API is a website.” No — a website returns pages for humans; an API usually returns data for software. They share HTTP, but the audience differs.
- “If the UI works, the API works.” The UI often hides or retries errors. An endpoint can be badly broken while the screen papers over it.
- “JSON and JavaScript are the same thing.” JSON is only a text data format. It borrows JavaScript’s object syntax, but every language reads and writes JSON.
- “A 200 means my test passed.” A 200 only means the request succeeded; you still must check the body is correct.
- “REST and SOAP are competing versions of the same thing.” They are different styles; REST is an approach, SOAP is a strict protocol.
Tutor tip: learn to speak the contract
Great API testers think in terms of the contract: “For this request, what exactly has the API promised to return?” Status code, shape of the body, data types, and error behaviour are all part of that promise. If you can describe the contract for an endpoint in one or two sentences, you already know what your tests must prove. Keep asking “what did it promise, and did it keep the promise?” — that single question drives almost everything in this course.
Hands-on exercise
No tools needed beyond a browser for parts 1–2; use JSONPlaceholder.
- In your browser, open
https://jsonplaceholder.typicode.com/users/3. Read the JSON that comes back. Write down: the user’s name, email, and thecityinside the nestedaddressobject. - Open
https://jsonplaceholder.typicode.com/posts?userId=1. How many posts come back? Is the top-level JSON value an object or an array? - On paper, label the parts of this endpoint:
https://api.shop.com/orders/88— protocol, host, resource, and which part identifies a specific order. - For a to-do app, list the resource and the correct HTTP method for: viewing all todos, viewing one todo, creating a todo, and deleting a todo.
- In one sentence each, explain to a non-technical friend what an API is and why a tester would test it directly instead of only clicking the screen.
Knowledge check
- In your own words, what is an API, and what does the “waiter” analogy illustrate?
- Name the two roles in the client–server model and say which one sends the request.
- Give two reasons REST is more popular than SOAP today.
- What is the difference between a resource and an endpoint?
- Give three reasons testers test APIs directly rather than only through the UI.
- In the test pyramid, where do API tests sit and why is that layer so valuable?
Show answers
- An API is an agreed set of rules that lets one piece of software ask another for data or an action. The waiter analogy shows the API as a messenger that carries your request to a hidden system and brings back the response, so you never touch the “kitchen” directly.
- The client and the server; the client sends the request.
- Any two of: REST is lighter and more readable, uses plain HTTP methods, typically uses compact JSON instead of verbose XML, and is simpler to build and consume.
- A resource is the thing (e.g. a user); an endpoint is the full address where you reach it (e.g.
https://api.example.com/users/42), combined with an HTTP method to form an operation. - Any three of: faster, earlier (backend ready before UI), more stable/less flaky, and more thorough (can send malformed or edge-case data the UI cannot).
- API tests sit in the middle layer. It is valuable because it gives broad, fast, stable coverage of business logic at low cost — far more than slow, flaky UI tests on top.
Key takeaways
- An API is a contract that lets software ask other software for data or actions, hiding the complexity behind it.
- The client–server model is the heartbeat of every API: client requests, server responds.
- A web service is an API delivered over the network via HTTP; REST (usually JSON) dominates, SOAP (XML) survives in legacy systems.
- Know the vocabulary cold: resource, endpoint, request, response, JSON.
- Testing APIs directly is faster, earlier, more stable and more thorough than UI testing — and it lives in the strong middle layer of the test pyramid.
Go deeper
Once the basics click, a few bigger ideas separate people who use APIs from people who can reason about them. The first is the API contract as a document. Most serious REST APIs publish a machine-readable spec in the OpenAPI (formerly Swagger) format — a file that lists every endpoint, method, parameter and response shape. Before you write a single test, skim the spec: it is the promise you are going to hold the API to, and tools can generate request stubs and even draft tests straight from it.
Second, REST is not the only style. You may meet GraphQL, where the client sends one query describing exactly the fields it wants ({ user(id: 42) { name email } }) to a single endpoint, and gRPC, a fast binary protocol used between back-end services. You still test the same way — send a request, assert on the response — but the request shape differs.
- Versioning: APIs evolve. A breaking change usually lands under a new version in the path (
/v2/users) or a header, so old clients keep working. Always confirm which version you are hitting. - Pagination: a collection like
GET /usersrarely returns everything at once — it returns a page, with links or a cursor to fetch the next. Testing “all users” means walking the pages, not trusting the first one. - Synchronous vs asynchronous: some requests do the work and answer immediately; others return
202 Acceptedand finish later, notifying you through a webhook (the server calls you back). Knowing which pattern an endpoint uses tells you whether to assert on the first response or to poll and wait.
