How an API Works: Request, Response and Endpoints Explained

Before you can test an API you need to see exactly what travels between the app and the server. In this lesson we follow one food order from the moment you tap “Place Order” until the confirmation appears, then break every API request and response into its parts: URL, method, headers, body, status code. Every concept is shown on a live endpoint you can call right now.

The Client-Server Model in Plain Words

Every API conversation has two sides:

• Client: whoever asks. It can be a mobile app, a website running in the browser, Postman, a Playwright test, or another backend service.
• Server: whoever answers. It receives the request, checks who you are, applies business rules, reads or writes the database, and replies.

The client and server can be written in totally different languages. A Swift iPhone app can talk to a Java server, which can talk to a Python pricing service. They understand each other because they agree on the same HTTP protocol and data format (usually JSON).

Step-by-Step: What Happens When You Place a Food Order

1. You tap Place Order. The app builds a request: POST https://api.foodapp.com/v1/orders with your token in the Authorization header and the items in a JSON body.
2. DNS converts api.foodapp.com into an IP address.
3. A secure HTTPS (TLS) connection is opened so nobody on the Wi-Fi can read the data.
4. An API gateway checks the token and the rate limit, then forwards the request to the order service.
5. The order service validates the items, asks the pricing service for the total, reserves stock and saves the order in the database.
6. The server replies 201 Created with the new order id and total.
7. The app reads the JSON and shows “Order placed! Arriving in 32 minutes.”

As a tester, steps 1 and 6 are what you control and observe. Everything in between is the “black box” you are testing through its API.

Anatomy of an API URL

Take this real endpoint from the SQA Tools practice API:

https://sqatools.in/wp-json/sqa-api/v1/users?role=admin&sort=age&order=desc

Everything up to and including the version is called the base URL: https://sqatools.in/wp-json/sqa-api/v1. Each resource path added to it, together with a method, is an endpoint.

Endpoint = Method + Path

The same path can be several endpoints, depending on the HTTP method:

The {id} part is a path parameter. You will study path and query parameters in depth in this lesson.

The 4 Parts of an API Request

1. Method (verb)

Tells the server what you want to do: GET read, POST create, PUT replace, PATCH update, DELETE remove. Full details in HTTP Methods.

2. URL (where)

Base URL + resource path + optional query string.

3. Headers (extra information about the request)

Content-Type: application/json      (the body I am sending is JSON)
Accept: application/json            (please answer in JSON)
Authorization: Bearer eyJhbGciOi... (this is who I am)
X-Request-Id: 7f3c-91aa             (trace id for debugging)

4. Body (payload, the data you send)

Used with POST, PUT and PATCH. GET and DELETE normally have no body.

{
  "name": "Laptop bag",
  "data": { "color": "black", "qty": 1 },
  "ttl": 120
}

The 3 Parts of an API Response

1. Status code

A 3-digit number that summarises the result. 2xx success, 3xx redirect, 4xx your (client) mistake, 5xx server failure. See the complete status code list.

2. Response headers

For example Content-Type, Location (URL of a newly created item), ETag (version for caching), Retry-After, and pagination headers such as X-Total-Count.

3. Response body

The data itself, or an error object. The practice API always uses the same error format, which is good API design and easy to assert:

{
  "error": {
    "status": 404,
    "code": "not_found",
    "message": "User 999 does not exist. Valid ids are 1 to 12."
  }
}

See a Full Request and Response Live

Press Send request to create a temporary object (it deletes itself after 2 minutes). Look at the status 201, the Location header and the ETag header in the result.

curl -i \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"Laptop bag","data":{"color":"black","qty":1},"ttl":120}' \
  "https://sqatools.in/wp-json/sqa-api/v1/objects"

Here is the same conversation written out as raw HTTP, which is how it really looks on the wire:

POST /wp-json/sqa-api/v1/objects HTTP/1.1
Host: sqatools.in
Content-Type: application/json
Accept: application/json

{"name":"Laptop bag","data":{"color":"black","qty":1},"ttl":120}

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Location: https://sqatools.in/wp-json/sqa-api/v1/objects/obj_hoeovqif1v
ETag: "v1"

{"id":"obj_hoeovqif1v","name":"Laptop bag","data":{"color":"black","qty":1},
 "version":1,"created_at":"2026-11-12T08:03:29Z","ttl_seconds":120, ...}

Writing the Same Request in Code

cURL

curl -i -X POST "https://sqatools.in/wp-json/sqa-api/v1/objects" \
  -H "Content-Type: application/json" \
  -d '{"name":"Laptop bag","data":{"color":"black","qty":1},"ttl":120}'

The -i flag prints response headers, which testers almost always want to see.

Playwright with TypeScript

import { test, expect } from '@playwright/test';

const BASE = 'https://sqatools.in/wp-json/sqa-api/v1';

test('create an object and read it back', async ({ request }) => {
  // 1. Request: method + URL + headers + body
  const create = await request.post(`${BASE}/objects`, {
    data: { name: 'Laptop bag', data: { color: 'black', qty: 1 }, ttl: 120 },
  });

  // 2. Response: status, headers, body
  expect(create.status()).toBe(201);
  const location = create.headers()['location'];
  const created = await create.json();
  expect(location).toContain(created.id);
  expect(created.version).toBe(1);

  // 3. Prove it was saved: GET the Location URL
  const read = await request.get(location);
  expect(read.ok()).toBeTruthy();
  expect((await read.json()).name).toBe('Laptop bag');
});

Passing an object to data makes Playwright set Content-Type: application/json automatically.

Synchronous vs Asynchronous APIs

Most REST calls are synchronous: you wait and get the result in the same response. Some work takes too long, like generating a 50-page bank statement. Then the API is asynchronous:

1. POST /statements returns 202 Accepted with a job id.
2. The client polls GET /statements/jobs/{id} until the status is "done", or the server calls the client back with a webhook.

Testing async APIs means checking the 202, the job status changes, timeouts and the final result. We cover webhooks in a later module.

Stateless: Why Every Request Must Carry Everything

REST APIs are stateless: the server does not remember your previous request. That is why your token goes in every request header. For testers this means:

• Each test can be run alone, in any order, which makes parallel automation easy.
• If a test passes only after another test ran first, it has a hidden dependency. Create your own test data inside each test instead.

Common Mistakes Beginners Make

• Checking only the status code and not the body. A 200 with the wrong total is still a bug.
• Forgetting Content-Type: application/json when sending a JSON body by hand (cURL). The practice API answers 415 Unsupported Media Type.
• Mixing up the base URL and the endpoint path, or adding double slashes.
• Not verifying that a create or update was really saved with a follow-up GET.
• Hardcoding ids that another tester or test run may delete.

Interview Questions: How APIs Work