DEV Community: azmiyuksel

I Tested a Star Wars API With Playwright, and It Was More Fun Than I Expected

azmiyuksel — Fri, 31 Jul 2026 12:56:02 +0000

I've written a fair number of Playwright tests, but almost all of them were UI tests — clicking buttons, filling forms, waiting for a modal to show up. At some point I wanted to get better at API testing specifically, and the annoying part was finding a decent playground API to practice on. Half of the "free public APIs" out there either require a signup, have a rate limit that kicks in after ten requests, or return data so bland you forget what you were even testing five minutes later.

Then I found funapi.dev, a small collection of mock REST APIs built specifically for testing practice. No signup, no API key for the read endpoints, and — the part that got me — one of the APIs is a Star Wars-themed one with characters, planets, and starships. That's exactly the kind of nonsense I want to be querying at 11pm instead of a generic "todos" API.

So I decided to write this post as a walkthrough: setting up Playwright for API testing from scratch, then writing a handful of real tests against the Star Wars API. If you're new to API testing, or new to Playwright in general, this should get you from zero to "okay, I actually understand what's happening" in about fifteen minutes.

Why bother with an API test instead of a UI test?

Quick tangent, because I think this matters for beginners. UI tests are slow and a bit brittle — a CSS class changes and your selector breaks. API tests, on the other hand, talk directly to the backend. They're fast, they don't care what your frontend looks like, and they're great for checking things like status codes, response shapes, and edge cases (what happens when you ask for a character that doesn't exist?).

Playwright isn't just a browser automation tool — it ships with an APIRequestContext that lets you send HTTP requests and make assertions on the response, completely independent of any browser. That's what we'll be using here.

The API we're working with

The Star Wars API on funapi.dev lives at:

https://funapi.dev/api/galaxy/v1

It covers three collections — planets, characters, and starships — and they're cross-referenced (a character has a homeworld, for example), which makes it more interesting to test than a flat list of objects. Some of the endpoints we'll touch:

GET /galaxy/v1/characters — list characters, with filtering and pagination
GET /galaxy/v1/characters/{id} — get one character
GET /galaxy/v1/characters/{id}/homeworld — a nested resource
POST /galaxy/v1/characters — requires a Bearer token
GET /galaxy/v1/starships/random — because why not
GET /galaxy/v1/planets — five planets, one of which is a swamp (you can guess which)

Everything here is a mock, so it resets and behaves predictably, which is exactly what you want when you're learning.

Setting things up

If you don't have a Playwright project yet, create one:

npm init playwright@latest

Pick TypeScript, and when it asks whether you want GitHub Actions, that's up to you — not needed for this tutorial. Once it's done, you'll have a tests/ folder and a playwright.config.ts. We won't touch most of the config, but it's worth pointing the baseURL at the API so our tests don't repeat the full URL every time.

In playwright.config.ts:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  use: {
    baseURL: 'https://funapi.dev/api/galaxy/v1',
  },
});

Now let's write some actual tests.

Test 1: listing characters

Create tests/characters.spec.ts:

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

test('returns a list of characters', async ({ request }) => {
  const response = await request.get('/characters');

  expect(response.ok()).toBeTruthy();
  expect(response.status()).toBe(200);

  const body = await response.json();
  expect(Array.isArray(body.results ?? body)).toBeTruthy();
});

A couple of notes for people newer to Playwright: the request fixture is injected automatically by the test runner, you don't need to import or configure it yourself as long as baseURL is set. response.ok() is a nice shortcut instead of manually checking status() >= 200 && status() < 300.

I wrote body.results ?? body because paginated list endpoints sometimes wrap results in an object ({ results: [...], next: ... }) and sometimes just return an array — worth checking the actual shape in your browser or with a quick console.log(body) before locking in your assertion. That's a small but very real lesson from doing this myself: don't assume the shape, check it first.

Test 2: getting a single character

test('returns one character by id', async ({ request }) => {
  const response = await request.get('/characters/1');
  expect(response.status()).toBe(200);

  const character = await response.json();
  expect(character).toHaveProperty('name');
  expect(character).toHaveProperty('id', 1);
});

This is the most basic form of an API test: hit the endpoint, check the status, check that the fields you expect are actually there. Simple, but it catches real bugs — like a field silently disappearing after a backend refactor.

Test 3: filtering by affiliation

The docs mention you can filter characters by their affiliation (rebel, empire, neutral — that kind of thing). This is a great case for testing query parameters:

test('filters characters by affiliation', async ({ request }) => {
  const response = await request.get('/characters', {
    params: { affiliation: 'rebel' },
  });

  expect(response.status()).toBe(200);

  const body = await response.json();
  const characters = body.results ?? body;

  for (const character of characters) {
    expect(character.affiliation?.toLowerCase()).toBe('rebel');
  }
});

I like this test because it's checking behavior, not just "did the server respond." Every item in the returned list should actually match the filter — that's the kind of thing that's easy to get subtly wrong on a backend (off-by-one in a WHERE clause, case sensitivity bugs, etc.).

Worth testing the opposite case too: a filter that matches nothing shouldn't blow up with a 500 or a 404, it should just come back with an empty list and a 200. That's actually called out on the funapi.dev docs page as something specifically worth practicing, so let's write it:

test('an impossible filter returns an empty list, not an error', async ({ request }) => {
  const response = await request.get('/characters', {
    params: { affiliation: 'definitely-not-a-real-faction' },
  });

  expect(response.status()).toBe(200);

  const body = await response.json();
  const characters = body.results ?? body;
  expect(characters.length).toBe(0);
});

This is a genuinely useful habit to build early: an empty result set is not an error, and your API (and your tests) should treat it that way.

Test 4: a nested resource

test('a character resolves to a homeworld', async ({ request }) => {
  const response = await request.get('/characters/1/homeworld');
  expect(response.status()).toBe(200);

  const homeworld = await response.json();
  expect(homeworld).toHaveProperty('name');
});

Nested resources are a good thing to get comfortable testing, because in real-world APIs they're where a lot of bugs live — mismatched IDs, stale references, N+1 query problems on the backend that only show up when you actually chain requests together.

Test 5: checking a 404

Every API guide says "test your error cases," and almost nobody does it in practice because it feels tedious. It takes four lines:

test('a nonexistent character returns 404', async ({ request }) => {
  const response = await request.get('/characters/999999');
  expect(response.status()).toBe(404);
});

That's it. But it's these tests that catch the annoying stuff — like an endpoint that returns 200 with an empty object instead of a proper 404, which then quietly breaks your frontend's error handling six months later.

Test 6: an unauthenticated write should fail

Creating a character requires a Bearer token. Before testing that a valid token works, it's worth confirming that the endpoint actually rejects requests without one:

test('creating a character without a token is rejected', async ({ request }) => {
  const response = await request.post('/characters', {
    data: {
      name: 'Some New Character',
      affiliation: 'neutral',
    },
  });

  expect(response.status()).toBe(401);
});

If you do have a token, testing the happy path looks like this:

test('creating a character with a valid token succeeds', async ({ request }) => {
  const response = await request.post('/characters', {
    headers: {
      Authorization: `Bearer ${process.env.GALAXY_API_TOKEN}`,
    },
    data: {
      name: 'Some New Character',
      affiliation: 'neutral',
    },
  });

  expect(response.status()).toBe(201);
  const created = await response.json();
  expect(created.name).toBe('Some New Character');
});

Small tip: never hardcode tokens directly in your test files, even for a mock API. Get into the habit of pulling them from environment variables now, so it's automatic once you're testing something that actually matters.

Running it

npx playwright test

Since these are pure API tests, they run fast — no browser is even launched for the request fixture tests, which is part of why API testing is such a good place to build confidence before jumping into UI automation.

Wrapping up

None of this is advanced stuff, and that's kind of the point. Status codes, response shape, filters that behave correctly on both matches and misses, nested resources, and one basic auth check — that combination covers most of what you actually need for real-world API testing. The Star Wars theme is just a nice excuse to not be bored while you practice it.

If you want to go further, funapi.dev also has pagination, rate limiting, ETags, and webhook signature scenarios set up on other mock APIs specifically for practicing those techniques — worth a look once the basics here feel comfortable.

If you write your own version of these tests, I'd genuinely like to see what you did differently — drop it in the comments.

API Testing With Postman: A Hands-On Walkthrough Using the Rick and Morty API

azmiyuksel — Wed, 29 Jul 2026 04:27:28 +0000

The hardest part of learning API testing isn't Postman. Postman is fine. The hard part is finding something to point it at.

I learned this the annoying way. When I started, our staging environment was the only API I had access to, and it was down roughly one day in three. When it was up, half my requests failed for reasons that had nothing to do with what I was practising — expired tokens, a colleague mid-deploy, a database someone had just truncated. I spent more time asking "is it me or is it the environment?" than actually learning.

So I went looking for a sandbox. Public APIs are easy to find, but most of them are read-only. You can GET all day and never touch a POST, never see a 401, never write a test that fails on purpose. Which is a problem, because in real QA work the interesting bugs live in the write paths and the error responses.

Then I found funapi.dev. It's a set of mock REST APIs — 37 of them, everything from a pizza ordering service to an OAuth 2.0 playground — built specifically so you can practise against them. No signup, no API key application form, no rate limit emails. And crucially, they're designed to return every status code you'd want to test, including the ugly ones.

I'm going to walk through one of them: the Rick and Morty API. By the end you'll have a working Postman collection with real assertions, and you'll have hit an auth wall, a 404, and a filter, on purpose.

What we're testing

Base URL:

https://funapi.dev/api/rickandmorty/v1

Nine endpoints across three resources. Here's the map (full docs here):

Characters

Method	Path	Notes
GET	`/characters`	Paginated, filter by status
GET	`/characters/{id}`	Single character
GET	`/characters/{id}/location`	Nested resource
POST	`/characters`	Bearer auth required
PUT	`/characters/{id}`	Bearer auth required
DELETE	`/characters/{id}`	Bearer auth required

Locations

Method	Path	Notes
GET	`/locations`	Filter by dimension

Episodes

Method	Path	Notes
GET	`/episodes`	Filter by episode code
GET	`/episodes/random`	Returns a random episode

The dataset is deliberately small — eight characters, a handful of locations, five episodes. That's a feature. Small datasets mean you can actually hold the expected state in your head, which makes it obvious when an assertion is wrong versus when the API is wrong.

Two things I want to flag before we start, because they're the reason I picked this API over a plain read-only one:

Three of the endpoints need a Bearer token. That gives us a real 401 to test.
There's a character in the dataset who is dead. Filtering on status actually returns different results, rather than the same list every time.

Setting up the collection

Open Postman, create a new collection, call it something like Rick and Morty API.

Before you create a single request, go to the collection's Variables tab and add:

Variable	Initial value	Current value
`baseUrl`	`https://funapi.dev/api/rickandmorty/v1`	same
`token`	`qa-admin-token`	same

I know it's tempting to skip this and paste the full URL into every request. Don't. The first time you need to point the same collection at a different host you'll be doing find-and-replace across twenty requests, and you'll miss one. Variables take ten seconds now.

(The tokens are qa-admin-token and qa-viewer-token — funapi.dev publishes them in its getting started guide. The viewer token is the interesting one, but we'll get to that.)

Request 1: list the characters

New request, GET, URL:

{{baseUrl}}/characters

Hit Send. You should get a 200 and a JSON body containing the list.

Look at the response body properly before you write anything else. Specifically, find out what wraps the array — some APIs return a bare array, some wrap it in data, some use results alongside a pagination object. Whatever key holds the array in your response is the key your assertions need to reference, and guessing here is the single most common reason a beginner's first test fails for no apparent reason.

Once you know the shape, go to the Scripts tab (older Postman versions call it Tests) and add:

pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Response is JSON", function () {
    pm.response.to.be.json;
});

pm.test("Responds in under 1000ms", function () {
    pm.expect(pm.response.responseTime).to.be.below(1000);
});

Send again. Three green checks at the bottom of the response pane.

Those three are worth putting on almost every request you ever write. They're cheap, and between them they catch a surprising share of real regressions — an endpoint that starts returning HTML because someone broke routing, or one that quietly gets ten times slower after a bad query change.

Now something with actual content in it:

pm.test("Character list is not empty", function () {
    const body = pm.response.json();
    const characters = body.data || body.results || body;
    pm.expect(characters.length).to.be.above(0);
});

pm.test("Each character has an id and a name", function () {
    const body = pm.response.json();
    const characters = body.data || body.results || body;
    characters.forEach(function (character) {
        pm.expect(character).to.have.property("id");
        pm.expect(character).to.have.property("name");
    });
});

The body.data || body.results || body line is a hedge so this works whatever envelope you got. In your own collection, once you've confirmed the shape, replace it with the actual path. Hedges in test code are a way of writing an assertion that can never fail, which defeats the point.

Request 2: filtering

This is where a lot of tutorials stop, and it's exactly where the bugs start.

{{baseUrl}}/characters?status=dead

Add the query param through Postman's Params tab rather than typing it into the URL bar — it's the same thing, but the table view is much easier to read when you're chaining three or four filters.

Now the assertion:

pm.test("Every returned character is dead", function () {
    const body = pm.response.json();
    const characters = body.data || body.results || body;

    pm.expect(characters.length).to.be.above(0);

    characters.forEach(function (character) {
        pm.expect(character.status.toLowerCase()).to.equal("dead");
    });
});

Two assertions in one test, and both matter. The length check is there because a filter that returns zero results will pass a forEach loop trivially — the loop body never runs, nothing gets asserted, test goes green. I have shipped that bug. A filter endpoint was returning an empty array for every query and my test suite was perfectly happy about it for two sprints.

If a filter test can pass on an empty response, it isn't testing the filter.

While you're here, try a value that shouldn't match anything — ?status=banana. What comes back? A 400 telling you the value isn't valid, or a 200 with an empty list? Both are defensible designs. Knowing which one your API does is the kind of thing that saves an argument later.

Request 3: the nested resource

{{baseUrl}}/characters/1/location

Nested routes like this are worth practising because they're where ID handling tends to break. Try it with an ID that definitely doesn't exist:

{{baseUrl}}/characters/99999/location

You should get a 404. Assert it:

pm.test("Unknown character returns 404", function () {
    pm.response.to.have.status(404);
});

pm.test("Error response has a message", function () {
    const body = pm.response.json();
    pm.expect(body).to.have.property("message");
});

That second test is the one people skip. A 404 with an empty body is technically correct and practically useless — your frontend has nothing to show the user. Checking that errors carry a readable message is a legitimate test, not padding.

Request 4: hitting the auth wall on purpose

Now the write endpoints. New request, POST to {{baseUrl}}/characters, with a JSON body:

{
  "name": "Birdperson",
  "status": "Alive",
  "species": "Bird-Person",
  "origin": "Bird World"
}

Send it without any auth header first.

That's the point.

pm.test("Unauthenticated POST is rejected", function () {
    pm.response.to.have.status(401);
});

Now add the auth. Go to the Authorization tab, pick Bearer Token, and put {{token}} in the field. Send again — you should get a 201, and the response should contain the character you just created.

pm.test("Character created", function () {
    pm.response.to.have.status(201);
});

pm.test("Created character echoes the name we sent", function () {
    const body = pm.response.json();
    const created = body.data || body;
    pm.expect(created.name).to.equal("Birdperson");
    pm.collectionVariables.set("createdCharacterId", created.id);
});

That last line is the trick that turns a pile of separate requests into an actual test flow. It grabs the ID out of the response and stores it in a collection variable, so the next request can use {{createdCharacterId}} instead of a hardcoded number. Chain a GET, a PUT and a DELETE behind it and you have a full CRUD lifecycle test that cleans up after itself.

Then try the same POST with qa-viewer-token instead of qa-admin-token. Different failure — 403, not 401. If the distinction is fuzzy: 401 means the API doesn't know who you are, 403 means it knows exactly who you are and you're not allowed. Testers get asked to explain this in interviews more often than you'd think.

Running the whole thing

Individual requests are fine while you're building. The payoff is running them together.

Open the collection, click Run. Postman fires every request in order and gives you a pass/fail summary.

Two things to check on your first run:

Order matters. If your DELETE runs before your POST, the delete has nothing to delete. Drag requests into a sensible sequence in the sidebar — that order is what the runner uses.

State leaks between runs. Run the collection twice. Does the second run pass? If your POST creates "Birdperson" and something in your suite asserts on a total character count, run two will fail. This is the single most valuable lesson the funapi.dev sandbox teaches you cheaply, because it's exactly what happens to real automated suites against real environments, usually at 2am in CI, usually when you're not on call but get called anyway.

Fix it the way you'd fix it in production: make each run either clean up what it created, or generate unique data. pm.variables.replaceIn('{{$randomFirstName}}') gives you a fresh name each run and takes about five seconds to wire up.

Where to go from here

Once the basic collection is green, funapi.dev has a few things worth graduating to:

Optimistic concurrency. The PUT endpoint supports ETag / If-Match. Send a stale ETag, get a 412. This is one of those concepts that stays abstract until you've watched it reject a request in front of you.
Idempotency keys. Send the same POST twice with the same Idempotency-Key header and see what happens. Then send it twice without one.
Export the collection. funapi.dev publishes an OpenAPI 3.1 spec and a ready-made Postman collection for each API. Import the spec, compare it to what you built by hand, and see what you missed. I missed two optional query params.
Run it headless. newman run collection.json gets you the same suite in a terminal, which is one small step from getting it into a CI pipeline.

The actual point

None of this is about Rick and Morty. It's that learning API testing needs an API that fails in interesting, predictable, repeatable ways — and staging environments fail in interesting, *un*predictable ways, which is a completely different and much less useful thing.

Get a sandbox. Break it on purpose. Write the test that catches it. Then go do the same thing to the API you actually get paid to test.

If you build something with this, the funapi.dev catalogue has 36 more APIs — the Coffee Shop one is home to a genuine 418, and the Fault Injection API lets you dial in latency and malformed payloads on demand. Both are more fun than they have any right to be.

API Testing with Python and pytest: Writing Real Tests Against a Live Mock API

azmiyuksel — Mon, 27 Jul 2026 08:20:01 +0000

Every time I want to teach someone API testing, I hit the same wall: there's nothing decent to test against.

Public APIs are either read-only (so you never touch a POST), rate-limited into uselessness, or they need a signup flow and a key in a .env file before anyone writes a single assertion. JSONPlaceholder is the usual fallback, but it fakes its writes — you POST something, get a 201, and the resource isn't there when you GET it. That's a terrible thing to learn on, because it teaches you that a status code is the same as a result.

I recently came across funapi.dev, which is a set of mock REST APIs built specifically for QA practice. No signup, no key. Writes actually persist. And — the part that made me sit up — each client gets its own isolated copy of the dataset.

I picked the Movies API and wrote a real suite against it. Below are the tests I found most worth showing, including the one that turned up a bug.

What we're testing

Base URL: https://funapi.dev/api/movies/v1

Nine endpoints, and they're chosen well. Filtering and sorting with strict query validation, full-text and fuzzy search, Bearer auth with two roles, range validation on ratings, and optimistic concurrency with If-Match. That covers most of what you'd actually assert against a production API.

A movie looks like this:

{
  "id": 1,
  "title": "Midnight Debugger",
  "genre": "thriller",
  "year": 2019,
  "rating": 7.8,
  "_v": 1
}

The titles are all QA in-jokes — Production Down, The 404 Identity, Gone in 60 Milliseconds. Ten seeded records, five per page.

Setup is two packages:

pip install pytest requests

The session wrapper

Before any tests, a small piece of plumbing that pays for itself immediately. I don't want BASE_URL + path scattered across forty call sites, and I definitely don't want to forget a timeout on one request and have CI hang for ten minutes.

Subclassing requests.Session handles both:

# conftest.py
import uuid
import pytest
import requests

BASE_URL = "https://funapi.dev/api/movies/v1"


class ApiSession(requests.Session):
    """A Session that prefixes the base URL and always sets a timeout."""

    def request(self, method, path, **kwargs):
        kwargs.setdefault("timeout", 10)
        return super().request(method, BASE_URL + path, **kwargs)

Now every call reads api.get("/movies"). Small thing, but it keeps the tests about behaviour instead of about URLs.

The isolation problem

Here's the issue that ruins most API test suites, and it shows up fast.

My third test deletes a movie. My fourth test asserts there are ten movies. Run them in that order and the fourth fails — not because anything is broken, but because the third one ate its data. So you start writing teardown code, or you order your tests by hand, or you give up and make everything read-only. All three are bad.

The Movies API solves this with an X-Sandbox-Id header. Send whatever string you like and you get a private copy of the dataset under that key. Omit it and the server assigns you one automatically (you can see it come back in the response headers as x-sandbox-id: auto_66685498c9e...).

So the fixture generates a fresh ID per test:

@pytest.fixture
def api():
    """An anonymous client pinned to its own throwaway copy of the dataset."""
    session = ApiSession()
    session.headers["X-Sandbox-Id"] = f"pytest-{uuid.uuid4().hex[:12]}"
    yield session
    session.close()


@pytest.fixture
def admin(api):
    api.headers["Authorization"] = "Bearer qa-admin-token"
    return api


@pytest.fixture
def viewer(api):
    api.headers["Authorization"] = "Bearer qa-viewer-token"
    return api

Every test now starts from the same ten movies and can destroy them freely. No teardown, no ordering constraints, and pytest -n auto works without a second thought. I proved it to myself with a test:

def test_two_sandboxes_do_not_see_each_others_writes(admin):
    admin.delete("/movies/1")

    other = ApiSession()
    other.headers["X-Sandbox-Id"] = f"pytest-{uuid.uuid4().hex[:12]}"
    try:
        assert other.get("/movies/1").status_code == 200
    finally:
        other.close()

If you're building your own mock service for a team, steal this idea. It's the single most useful property a test API can have.

Asserting the contract, not the data

The first real test checks the pagination envelope:

def test_list_returns_a_pagination_envelope(api):
    response = api.get("/movies")

    assert response.status_code == 200
    body = response.json()
    assert body["page"] == 1
    assert body["pageSize"] == 5
    assert body["totalPages"] == 2
    assert len(body["data"]) == body["pageSize"]

Note the last line. len(body["data"]) == body["pageSize"] rather than == 5. The response has to be internally consistent, which is the actual rule — hardcoding 5 just re-states the fixture.

Same instinct on the shape check:

EXPECTED_KEYS = {"id", "title", "genre", "year", "rating", "_v"}


def test_every_movie_has_the_documented_shape(api):
    for movie in api.get("/movies").json()["data"]:
        assert EXPECTED_KEYS <= set(movie), f"missing keys in {movie}"
        assert isinstance(movie["year"], int)
        assert 0 <= movie["rating"] <= 10

EXPECTED_KEYS <= set(movie) is a subset check, so the test survives the API adding a field. Breaking your suite because someone shipped a new optional attribute is a good way to get everyone to stop trusting it.

Sorting gets the same treatment — don't assert the titles, assert the ordering:

def test_sort_by_rating_is_actually_sorted(api):
    ratings = [m["rating"] for m in api.get("/movies", params={"sort": "rating"}).json()["data"]]

    assert ratings == sorted(ratings, reverse=True)

Negative tests, compressed

This is where parametrize earns its keep. The Movies API uses strict query validation, so it rejects unknown parameters instead of ignoring them — which means three distinct failure modes worth covering:

@pytest.mark.parametrize("params,status,fragment", [
    ({"sort": "banana"}, 400, "sort must be"),
    ({"colour": "red"},  400, "Unknown query parameter"),
    ({"page": 99},       404, "out of range"),
])
def test_bad_query_parameters_are_rejected(api, params, status, fragment):
    response = api.get("/movies", params=params)

    assert response.status_code == status
    assert fragment in response.json()["message"]

Three tests, seven lines, and each one reports its own name when it fails. The error bodies are properly descriptive too, which I appreciated:

{
  "error": "Not Found",
  "message": "page 99 is out of range (last page is 2).",
  "requestId": "6d8e8e715a99a951"
}

Rating validation is a boundary problem, so it gets the boundaries:

@pytest.mark.parametrize("rating", [-1, 10.1, 42, "eight"])
def test_ratings_outside_zero_to_ten_are_rejected(admin, rating):
    response = admin.put("/movies/1/rating", json={"rating": rating})

    assert response.status_code == 400
    assert "between 0 and 10" in response.json()["message"]


@pytest.mark.parametrize("rating", [0, 5.5, 10])
def test_ratings_inside_the_range_are_accepted(admin, rating):
    response = admin.put("/movies/1/rating", json={"rating": rating})

    assert response.status_code == 200
    assert response.json()["rating"] == rating

0 and 10 are the ones that matter. Off-by-one on an inclusive range is a genuinely common bug, and it's invisible if you only ever test with 7.

Auth is two tests, not one

A missing token and a valid-but-insufficient token are different failures, and plenty of suites only check the first:

def test_writing_without_a_token_is_401(api):
    response = api.post("/movies", json={"title": "Anonymous", "genre": "drama"})

    assert response.status_code == 401


def test_viewer_cannot_delete(viewer):
    response = viewer.delete("/movies/3")

    assert response.status_code == 403
    assert "viewer role" in response.json()["message"]


def test_admin_can_delete_and_the_movie_stays_gone(admin):
    assert admin.delete("/movies/3").status_code == 204
    assert admin.get("/movies/3").status_code == 404

That last test is the one JSONPlaceholder can't give you. The delete returns 204, and then the follow-up GET returns 404 because the record is genuinely gone from my sandbox. A status code on its own proves nothing; the read-back is the assertion.

The bug

Now the fun part. POST /movies requires an admin token, and the docs list six genres: thriller, drama, comedy, horror, action, documentary. So:

response = admin.post("/movies", json={"title": "Bad genre", "genre": "musical", "year": 2025})

201 Created. It cheerfully stored a musical.

It gets better. Post a body with nothing but a title and you get back a complete record with invented defaults:

{"id": 12, "title": "No genre", "genre": "drama", "year": 2026, "rating": null}

So PUT /movies/{id}/rating validates its input carefully and returns a clean 400 for anything out of range, while POST /movies accepts more or less whatever you hand it. That inconsistency between a create endpoint and an update endpoint on the same resource is extremely realistic — I've filed this exact bug against real services more than once. Validation gets written when someone remembers, and nobody remembers on every route.

I left it in the suite as a strict xfail rather than deleting it:

@pytest.mark.xfail(reason="POST /movies does not validate genre — reported upstream", strict=True)
def test_post_rejects_an_invalid_genre(admin):
    response = admin.post("/movies", json={"title": "Bad genre", "genre": "musical", "year": 2025})

    assert response.status_code == 400

strict=True is the important bit. The test is expected to fail, and if it ever passes, pytest fails the run and tells me — which is exactly what I want the day someone patches it. A commented-out test just rots.

One more: optimistic concurrency

The _v field on each movie isn't decoration. The rating endpoint honours If-Match, so you can test the lost-update scenario:

def test_stale_if_match_is_rejected(admin):
    first = admin.put("/movies/2/rating", json={"rating": 5}, headers={"If-Match": '"v1"'})
    assert first.status_code == 200
    assert first.json()["_v"] == 2

    second = admin.put("/movies/2/rating", json={"rating": 6}, headers={"If-Match": '"v1"'})
    assert second.status_code == 412

Two clients read version 1, both try to write, the second one gets 412 Precondition Failed instead of silently clobbering the first. Being able to reproduce that in a unit test without spinning up threads is worth a lot.

One gotcha: the version token here is "v1", not the ETag value from the response header. I burned about ten minutes on that before reading the error message properly, which was telling me the answer the whole time.

Where this leaves us

Those few files cover pagination, filtering, sorting, search, auth, role permissions, boundary validation, and concurrency control. Nothing mocked, nothing stubbed — real HTTP against a real server, which means they also catch the things a mocked test never will.

If you want to take it further, this structure drops straight into GitHub Actions (no secrets to configure, which is the nicest part), and funapi.dev exports an OpenAPI 3.1 spec per API if you'd rather do schema validation with something like schemathesis. There's also a Fault Injection API on the same site for testing retry and timeout logic, which is my next thing to write about.

The larger point, though, is the sandbox header. Isolated-by-default test data is what let me write all of this without a single setup/teardown block or one line of cleanup code. If you own an internal API that other teams write tests against, that's the feature to build.

If you spot something I should be asserting and I'm not, tell me in the comments — I'd rather find out from you than from production.

I Tried to curl a Mock World Cup 2026 API and Got Nothing — Here's Why Playwright Was the Right Tool

azmiyuksel — Fri, 24 Jul 2026 06:18:34 +0000

I was looking for a REST API to practice API testing on that wasn't yet another "todo list" or "fake store" clone, and I landed on funapi.dev — a free, no-signup playground with a few dozen mock APIs, everything from a Harry Potter API to a bank API with a deliberately broken 402. One of them caught my eye immediately: a full World Cup 2026 API, with 48 teams, live group standings, a Golden Boot leaderboard, ticket purchases that can actually sell out, and match simulation.

I figured it'd be a fun, low-stakes target for a Playwright test suite. It was — but not for the reason I expected. The interesting part of this post isn't really the football data. It's a gotcha I ran into before I wrote a single expect().

First move: curl it

Old habit — before opening an editor, I like to poke an API from the terminal.

curl https://funapi.dev/api/worldcup/v1/teams

Nothing. No JSON, no error, no response at all. I tried it in a plain fetch() from Node too. Same result. My first assumption was that the endpoint needed a header I was missing, or that I'd mistyped the base path. Neither was true.

Here's what's actually going on: funapi.dev doesn't run these APIs on a backend server at all. Every mock API on the site — World Cup 2026 included — is implemented inside a Service Worker that gets registered the moment you load a page on the domain. You can check this yourself in DevTools, or just ask the page:

const regs = await navigator.serviceWorker.getRegistrations();
console.log(regs.map(r => r.active?.scriptURL));
// → ["https://funapi.dev/sw.js"]

fetch() calls made inside a real browser tab on that origin get intercepted by sw.js and answered with realistic mock JSON, correct status codes, pagination, the works. fetch() calls made from curl, Postman, or a Node script never touch a browser, so there's no service worker to intercept them — they just fall through to the static site, which has nothing to say about /api/worldcup/v1/teams.

Once I understood that, the choice of Playwright stopped being "a tool I happened to like" and became the actually correct tool for the job. Postman and plain HTTP clients are structurally unable to talk to this API. You need something that drives a real browser engine.

The second gotcha: Playwright has two HTTP clients

This is the part that got me. Playwright ships an APIRequestContext (the request fixture) specifically for testing APIs without spinning up a browser page — it's fast, and it's the officially recommended way to hit REST endpoints in a Playwright test.

It also doesn't work here, for the exact same reason curl doesn't. request.get() fires from Playwright's own Node process, not from inside a page, so it bypasses the service worker just like curl did. I only caught this because my first attempt returned a 404 from the static host instead of the mock response I expected.

The fix is to keep the fetch inside the page, using page.evaluate():

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

async function api<T = any>(
  page: Page,
  path: string,
  init?: { method?: string; token?: string }
): Promise<{ status: number; body: T }> {
  return page.evaluate(
    async ({ path, init }) => {
      const headers: Record<string, string> = {};
      if (init?.token) headers['Authorization'] = `Bearer ${init.token}`;
      const res = await fetch(path, { method: init?.method ?? 'GET', headers });
      return { status: res.status, body: await res.json() };
    },
    { path, init }
  );
}

Every test navigates to a page on the funapi.dev origin first (I used the docs page for the World Cup API) and waits for the service worker to be ready, then routes all its requests through this helper instead of request.get().

Writing tests against actual endpoints

The API has 17 endpoints across teams, matches, venues, players, tickets, and a "fanzone" group with mascots and champion predictions. I didn't try to cover all of it — I picked a handful of tests that exercise real behavior instead of just happy-path smoke checks.

test.describe('World Cup 2026 API (funapi.dev)', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('https://funapi.dev/docs/worldcup');
    await page.evaluate(() => navigator.serviceWorker.ready);
  });

  test('lists all 48 qualified teams, hosts included', async ({ page }) => {
    const { status, body } = await api(page, '/api/worldcup/v1/teams');

    expect(status).toBe(200);
    expect(body.total).toBe(48);

    const hosts = body.data.filter((t: any) => t.host);
    expect(hosts.map((t: any) => t.code).sort()).toEqual(['CAN', 'MEX', 'USA']);
  });

  test('rejects unknown query parameters instead of silently ignoring them', async ({ page }) => {
    const { status, body } = await api(page, '/api/worldcup/v1/teams?limit=3');

    expect(status).toBe(400);
    expect(body.message).toMatch(/unknown query parameter/i);
  });

  test('blocks the goal timeline until the match has actually been played', async ({ page }) => {
    const { status, body } = await api(page, '/api/worldcup/v1/matches/1/events');

    expect(status).toBe(409);
    expect(body.message).toMatch(/simulate/i);
  });

  test('requires a bearer token before it will simulate a match', async ({ page }) => {
    const { status, body } = await api(page, '/api/worldcup/v1/matches/1/simulate', {
      method: 'POST',
    });

    expect(status).toBe(401);
    expect(body.message).toMatch(/bearer token/i);
  });
});

A couple of things worth calling out here, because they're the reason I picked these particular tests over just asserting status === 200 everywhere:

The 400 on unknown query params is a real design choice worth testing. A lot of production APIs silently ignore parameters they don't recognize, which means a typo like ?limt=10 slips past code review and just quietly returns an unfiltered list — a bug that's genuinely annoying to track down later. This API uses strict query validation and fails loudly instead. That's exactly the kind of behavior I want a regression test pinned on, so nobody "fixes" it into permissiveness by accident.

The 409 on /matches/{id}/events models a real state machine. You can't get a goal timeline for a match that hasn't been simulated yet — the API tells you so explicitly, with a message pointing at the endpoint you need to call first (POST /matches/{id}/simulate). Testing the "wrong order of operations" path is usually more valuable than testing the happy path, and it's the kind of case that's easy to skip when you're just trying to get a suite green.

The 401 on the simulate endpoint checks auth is actually enforced, not just documented. The docs list this endpoint as requiring a Bearer token (qa-admin-token for admin-only actions, qa-viewer-token for read-level access, per the getting started guide) — but "the docs say so" and "the server actually rejects unauthenticated requests" are two different claims, and only one of them is worth trusting without a test.

I also threw in a couple of low-effort smoke tests for the Golden Boot leaderboard and the tournament mascots (Maple the moose, Zayu the jaguar, and Clutch the bald eagle, if you're curious), mostly to prove the pattern generalizes past the teams and matches resources.

Running it

Nothing unusual on the setup side, since the trick is entirely in how the requests are made, not in the Playwright config:

npm init playwright@latest
npx playwright test worldcup-api.spec.ts

One thing I'd flag if you're adapting this: don't run the suite in parallel against shared state you didn't reset. The mock backend keeps state (matches once simulated stay simulated, tickets once sold stay sold) for the lifetime of the service worker, so if you write tests that buy tickets or simulate matches, either isolate them or expect order to matter.

Takeaway

The football data was fun, but the actual lesson was about test design, not sports trivia: check what layer your API actually lives at before you reach for the "obvious" tool. I almost wrote this whole suite with request.get() out of habit, and it would have failed in a confusing way that had nothing to do with my assertions. A quick look at how the target actually serves responses — in this case, a Service Worker instead of a server — changed which Playwright feature was even the right one to reach for.

If you want to poke at it yourself, the full API reference (with a "Try it out" console, an OpenAPI spec, and a Postman collection) is at funapi.dev/docs/worldcup.

I Tested a Fake Detective Agency's API with Cypress (and It Was Actually Useful)

azmiyuksel — Thu, 23 Jul 2026 09:42:55 +0000

I've been meaning to write some API tests outside of work for a while now, mostly to keep my Cypress skills from going rusty between projects. The problem is always the same: I don't have a spare API lying around to poke at, and spinning up my own Express server just to practice cy.request() felt like more setup than the practice was worth.

A few days ago I stumbled on funapi.dev while looking for exactly that — a free, no-signup mock API I could throw requests at without owning the backend. It's a whole playground of fandom-themed mock APIs (Harry Potter, Star Wars, The Office, you name it), but the one that caught my eye was the Sherlock Holmes API. Five cases, a cast of suspects, some clues, Bearer auth on the write endpoints, and — this is the part that sold me — an endpoint that returns a 409 if you try to update something to a status it's already in. That's a real pattern I've had to test at work before, so it felt worth writing up.

This post is basically me working through that API in Cypress, endpoint by endpoint, including the part where I tripped over the 409 myself before I meant to.

What you're working with

Base URL:

https://funapi.dev/api/holmes/v1

Reading data needs nothing — no key, no signup. Writing data (POST, PUT, PATCH, DELETE) needs a Bearer token, and funapi.dev conveniently ships two of them for testing: qa-admin-token, which can actually write, and qa-viewer-token, which gets politely rejected if you try to write with it. Every caller also gets its own sandboxed copy of the data behind the scenes, so if you and I both run this suite at the same time, we're not stepping on each other's test data. That's a nice touch if you ever wire this into CI.

Setup

Nothing fancy here:

npm install cypress --save-dev
npx cypress open

I set the API as the baseUrl in cypress.config.js so I could write relative paths instead of the full URL every time:

const { defineConfig } = require("cypress");

module.exports = defineConfig({
  e2e: {
    baseUrl: "https://funapi.dev/api/holmes/v1",
  },
});

Test file: cypress/e2e/sherlock-holmes-api.cy.js.

Starting simple: GET /cases

First thing I did was just hit /cases and look at what came back:

{
  "total": 5,
  "data": [
    { "id": 1, "title": "The Vanishing Violin", "status": "solved", "year": 1889 },
    { "id": 2, "title": "The Crimson Cipher", "status": "solved", "year": 1891 },
    { "id": 3, "title": "The Baker Street Burglary", "status": "open", "year": 1894 },
    { "id": 4, "title": "The Midnight Telegram", "status": "solved", "year": 1896 },
    { "id": 5, "title": "The Fogbound Heir", "status": "open", "year": 1899 }
  ],
  "requestId": "…"
}

Five cases, two still open. Easy enough to write a first test around:

describe("Sherlock Holmes API (funapi.dev)", () => {
  it("GET /cases returns the full case list", () => {
    cy.request("GET", "/cases").then((response) => {
      expect(response.status).to.eq(200);
      expect(response.body).to.have.property("total", 5);
      expect(response.body.data).to.have.length(5);
      expect(response.body.data[0]).to.include.keys(
        "id",
        "title",
        "status",
        "year"
      );
    });
  });
});

Filtering, and making the API say no on purpose

/cases takes a status query param — open or solved. That's worth testing both ways: once for the filter actually working, and once for what happens when you feed it nonsense.

it("GET /cases?status=open only returns open cases", () => {
  cy.request("GET", "/cases?status=open").then((response) => {
    expect(response.status).to.eq(200);
    response.body.data.forEach((c) => {
      expect(c.status).to.eq("open");
    });
  });
});

it("GET /cases with a garbage status value returns 400", () => {
  cy.request({
    method: "GET",
    url: "/cases?status=bribed",
    failOnStatusCode: false,
  }).then((response) => {
    expect(response.status).to.eq(400);
  });
});

Quick note on failOnStatusCode: false in case you haven't run into it: Cypress fails the test the moment cy.request() gets anything outside 2xx, unless you tell it not to. Forget that flag on a test that's expecting a 400 and you'll spend ten confused minutes wondering why your assertion never even runs.

Nested resource: suspects per case

/cases/{id}/suspects was the one that made me trust this API a bit more — it's a proper nested resource, not just a flat list with a filter bolted on:

{
  "case": "The Vanishing Violin",
  "suspects": [
    { "id": 1, "name": "Ambrose Reed", "alibi": "at the opera", "caseId": 1, "guilty": false, "_v": 1 },
    { "id": 2, "name": "Clara Whitfield", "alibi": "none given", "caseId": 1, "guilty": true, "_v": 1 }
  ]
}

it("GET /cases/:id/suspects returns suspects for that case", () => {
  cy.request("GET", "/cases/1/suspects").then((response) => {
    expect(response.status).to.eq(200);
    expect(response.body.case).to.eq("The Vanishing Violin");
    expect(response.body.suspects.length).to.be.greaterThan(0);
    expect(response.body.suspects[0]).to.include.keys(
      "id",
      "name",
      "alibi",
      "caseId",
      "guilty",
      "_v"
    );
  });
});

(Clara Whitfield's alibi is literally "none given," which, if you ask me, is not a great look for her.)

Auth: proving the door is actually locked

Anything that writes — POST /suspects, PUT/DELETE /suspects/{id}, PATCH /cases/{id} — wants a Bearer token. Before testing that the token works, I like to test that its absence actually gets rejected. It sounds obvious, but I've seen "protected" endpoints in the wild that quietly accept unauthenticated requests because someone forgot a middleware somewhere. Cheap test, real value.

it("PATCH /cases/:id without a token returns 401", () => {
  cy.request({
    method: "PATCH",
    url: "/cases/3",
    body: { status: "solved" },
    failOnStatusCode: false,
  }).then((response) => {
    expect(response.status).to.eq(401);
  });
});

Then the version with a real token:

const ADMIN_TOKEN = "qa-admin-token";

it("PATCH /cases/:id updates an open case to solved", () => {
  cy.request({
    method: "PATCH",
    url: "/cases/3", // "The Baker Street Burglary" — open in the seed data
    headers: { Authorization: `Bearer ${ADMIN_TOKEN}` },
    body: { status: "solved" },
  }).then((response) => {
    expect(response.status).to.eq(200);
    expect(response.body.status).to.eq("solved");
  });
});

The 409 I found by accident

Here's the part I mentioned earlier. While poking around in the docs' "try it out" panel before writing any actual test code, I patched case 1 ("The Vanishing Violin," already marked solved in the seed data) to solved again, expecting a boring 200. Instead I got a 409. Turns out the API treats "update a resource to the status it's already in" as a conflict rather than a no-op, which is a genuinely useful thing to test for — it's the same shape of bug as an order-status endpoint letting you "cancel" an already-cancelled order.

it("PATCH /cases/:id to its current status returns 409", () => {
  cy.request({
    method: "PATCH",
    url: "/cases/1",
    headers: { Authorization: `Bearer ${ADMIN_TOKEN}` },
    body: { status: "solved" },
    failOnStatusCode: false,
  }).then((response) => {
    expect(response.status).to.eq(409);
  });
});

POST with an Idempotency-Key

POST /suspects adds a suspect to a case, and it accepts an Idempotency-Key header — send the same key twice and you get the original response back instead of a duplicate row. That's the kind of thing that's easy to forget to test until a flaky network retry duplicates a real order in production, so I added it here too:

it("POST /suspects creates a new suspect", () => {
  cy.request({
    method: "POST",
    url: "/suspects",
    headers: {
      Authorization: `Bearer ${ADMIN_TOKEN}`,
      "Idempotency-Key": `cy-${Date.now()}`,
    },
    body: {
      name: "Mr. Hartley",
      alibi: "claims he was asleep",
      caseId: 3,
    },
  }).then((response) => {
    expect(response.status).to.eq(201);
    expect(response.body).to.include({
      name: "Mr. Hartley",
      caseId: 3,
    });
  });
});

One for the schema-checkers: /clues/random

/clues/random, as the name says, hands back a different clue every time, so there's nothing fixed to assert on except shape. Still worth having — it's a cheap contract test that'll catch a field getting renamed or dropped.

it("GET /clues/random always returns a well-formed clue", () => {
  cy.request("GET", "/clues/random").then((response) => {
    expect(response.status).to.eq(200);
    expect(response.body).to.include.keys(
      "id",
      "description",
      "caseId",
      "type"
    );
  });
});

The whole file

Here's everything above stitched into one spec, cypress/e2e/sherlock-holmes-api.cy.js:

const ADMIN_TOKEN = "qa-admin-token";

describe("Sherlock Holmes API (funapi.dev)", () => {
  it("GET /cases returns the full case list", () => {
    cy.request("GET", "/cases").then((response) => {
      expect(response.status).to.eq(200);
      expect(response.body).to.have.property("total", 5);
      expect(response.body.data).to.have.length(5);
      expect(response.body.data[0]).to.include.keys(
        "id",
        "title",
        "status",
        "year"
      );
    });
  });

  it("GET /cases?status=open only returns open cases", () => {
    cy.request("GET", "/cases?status=open").then((response) => {
      expect(response.status).to.eq(200);
      response.body.data.forEach((c) => {
        expect(c.status).to.eq("open");
      });
    });
  });

  it("GET /cases with a garbage status value returns 400", () => {
    cy.request({
      method: "GET",
      url: "/cases?status=bribed",
      failOnStatusCode: false,
    }).then((response) => {
      expect(response.status).to.eq(400);
    });
  });

  it("GET /cases/:id/suspects returns suspects for that case", () => {
    cy.request("GET", "/cases/1/suspects").then((response) => {
      expect(response.status).to.eq(200);
      expect(response.body.case).to.eq("The Vanishing Violin");
      expect(response.body.suspects.length).to.be.greaterThan(0);
      expect(response.body.suspects[0]).to.include.keys(
        "id",
        "name",
        "alibi",
        "caseId",
        "guilty",
        "_v"
      );
    });
  });

  it("PATCH /cases/:id without a token returns 401", () => {
    cy.request({
      method: "PATCH",
      url: "/cases/3",
      body: { status: "solved" },
      failOnStatusCode: false,
    }).then((response) => {
      expect(response.status).to.eq(401);
    });
  });

  it("PATCH /cases/:id updates an open case to solved", () => {
    cy.request({
      method: "PATCH",
      url: "/cases/3",
      headers: { Authorization: `Bearer ${ADMIN_TOKEN}` },
      body: { status: "solved" },
    }).then((response) => {
      expect(response.status).to.eq(200);
      expect(response.body.status).to.eq("solved");
    });
  });

  it("PATCH /cases/:id to its current status returns 409", () => {
    cy.request({
      method: "PATCH",
      url: "/cases/1",
      headers: { Authorization: `Bearer ${ADMIN_TOKEN}` },
      body: { status: "solved" },
      failOnStatusCode: false,
    }).then((response) => {
      expect(response.status).to.eq(409);
    });
  });

  it("POST /suspects creates a new suspect", () => {
    cy.request({
      method: "POST",
      url: "/suspects",
      headers: {
        Authorization: `Bearer ${ADMIN_TOKEN}`,
        "Idempotency-Key": `cy-${Date.now()}`,
      },
      body: {
        name: "Mr. Hartley",
        alibi: "claims he was asleep",
        caseId: 3,
      },
    }).then((response) => {
      expect(response.status).to.eq(201);
      expect(response.body).to.include({
        name: "Mr. Hartley",
        caseId: 3,
      });
    });
  });

  it("GET /clues/random always returns a well-formed clue", () => {
    cy.request("GET", "/clues/random").then((response) => {
      expect(response.status).to.eq(200);
      expect(response.body).to.include.keys(
        "id",
        "description",
        "caseId",
        "type"
      );
    });
  });
});

Run it:

npx cypress run --spec "cypress/e2e/sherlock-holmes-api.cy.js"

All eight pass for me, in about a second and a half, which is roughly seven seconds faster than the equivalent UI test would've taken just to load a login page.

Why I'd actually recommend this over a toy backend

None of this is really about Sherlock Holmes, obviously. Strip the theme away and what's left is a pretty normal shape for an API test suite: a happy-path GET, a filtered GET, a deliberately broken GET, an unauthenticated write that should fail, an authenticated write that should succeed, a conflict case, an idempotent POST, and a loose schema check on something unpredictable. That's most of what I'd write against a real API at work, minus the fictional detective agency.

The advantage of doing this against funapi.dev instead of mocking everything with cy.intercept() is that you're hitting a real server and getting real HTTP behavior back — actual status codes, actual timing, actual auth rejection. It's a better rep for the muscle memory than a fixture file ever is. And if you want to go further, funapi.dev has an OpenAPI spec and Postman collection for this API (and the 24 others) that you can pull into whatever contract-testing setup you're already using.

If you try this out, I'd extend it with PUT/DELETE on /suspects/{id} next, plus a test confirming qa-viewer-token gets rejected on writes — I ran out of case file to look through before I got to those, but they're on my list.

If you've found other mock APIs worth practicing on, drop them in the comments — always looking for new ones to break.

Rest Assured Tutorial for Beginners: Testing a Real REST API in Java

azmiyuksel — Wed, 22 Jul 2026 11:18:06 +0000

I've written a lot of API tests over the years, and the ones that stuck with me weren't the ones testing some abstract "users" endpoint from a textbook. They were the ones where the data was fun enough that I actually wanted to poke at it. So instead of the usual placeholder API, this tutorial uses a small Harry Potter–themed REST API — houses, students, spells — to walk through Rest Assured from zero.

By the end you'll know how to send GET and POST requests, assert on status codes and JSON bodies, work with query parameters, and test an endpoint that requires a Bearer token. No prior Rest Assured experience needed, just some basic Java.

What you'll need

JDK 11 or newer
Maven (or Gradle, if you'd rather adapt the examples)
Any IDE — IntelliJ, Eclipse, VS Code, doesn't matter
About 30 minutes

The API we're testing against

We'll hit the Harry Potter API, a free mock REST API with no signup required. It's part of a larger playground called Fun API Playground that has a bunch of these themed sandboxes (Star Wars, Pokémon, a fake bank, that sort of thing) — useful if you want more practice material after this, but not the point of this post. It exists specifically so people can throw real HTTP requests at something without setting up their own backend first.

The base URL we'll use is:

https://funapi.dev/api/wizarding/v1

It has ten endpoints covering houses, students, and spells. Most are open reads; a few (enrolling or updating a student) need a Bearer token. That mix is actually perfect for a beginner tutorial because you get to practice both the easy case and the "wait, why is this returning 401" case.

Setting up the project

Create a Maven project and add these to your pom.xml:

<dependencies>
    <dependency>
        <groupId>io.rest-assured</groupId>
        <artifactId>rest-assured</artifactId>
        <version>5.4.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.10.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Rest Assured pulls in Hamcrest matchers automatically, which is what gives you that readable equalTo(...), hasItem(...) style of assertion later on. Check Maven Central if you want the latest patch versions — the numbers above were current as of writing.

Your first test: GET /houses

Let's start with the simplest possible request — listing the four houses.

import io.restassured.RestAssured;
import org.junit.jupiter.api.Test;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.*;

public class HousesTest {

    @Test
    void listAllHouses() {
        RestAssured.baseURI = "https://funapi.dev/api/wizarding/v1";

        given()
        .when()
            .get("/houses")
        .then()
            .statusCode(200)
            .body("total", equalTo(4))
            .body("data.name", hasItems("Gryffindor", "Slytherin", "Hufflepuff", "Ravenclaw"));
    }
}

Run that and it should pass. If you want to see what you're actually asserting against, the response looks like this:

{
  "total": 4,
  "data": [
    { "id": 1, "name": "Gryffindor", "founder": "Godric Gryffindor", "traits": ["courage", "bravery", "daring"], "element": "fire", "points": 472 },
    { "id": 2, "name": "Slytherin", "founder": "Salazar Slytherin", "traits": ["ambition", "cunning", "resourcefulness"], "element": "water", "points": 452 },
    { "id": 3, "name": "Hufflepuff", "founder": "Helga Hufflepuff", "traits": ["patience", "loyalty", "fairness"], "element": "earth", "points": 428 },
    { "id": 4, "name": "Ravenclaw", "founder": "Rowena Ravenclaw", "traits": ["wisdom", "wit", "creativity"], "element": "air", "points": 461 }
  ],
  "requestId": "ba44d86001332ca8"
}

Notice data.name in the test — Rest Assured lets you dot into nested JSON like that without writing a single POJO. That's most of the appeal for quick API checks.

Digging deeper into the JSON body

Let's check Gryffindor specifically, by filtering the array with a Groovy-style expression Rest Assured understands out of the box:

@Test
void gryffindorHasFireElement() {
    given()
    .when()
        .get("/houses")
    .then()
        .statusCode(200)
        .body("find { it.name == 'Gryffindor' }.element", equalTo("fire"))
        .body("find { it.name == 'Gryffindor' }.traits", hasItem("bravery"));
}

If you'd rather not memorize that Groovy syntax right away, extracting the body as a JsonPath object and reading values off it works just as well and is arguably easier to follow when you're starting out:

@Test
void gryffindorHasFireElementUsingJsonPath() {
    JsonPath json = given()
        .when()
        .get("/houses")
        .jsonPath();

    int gryffindorId = json.getInt("data.find { it.name == 'Gryffindor' }.id");
    assertEquals(1, gryffindorId);
}

Both approaches are common in real test suites. Pick whichever reads more naturally to you.

Working with query and path parameters

The students endpoint supports pagination and filtering by house, which is a good excuse to practice query params:

@Test
void filterStudentsByHouse() {
    given()
        .queryParam("houseId", 1)
        .queryParam("page", 1)
    .when()
        .get("/students")
    .then()
        .statusCode(200)
        .body("data.houseId", everyItem(equalTo(1)));
}

And fetching a single resource by path parameter looks like this:

@Test
void getOneStudent() {
    given()
        .pathParam("id", 1)
    .when()
        .get("/students/{id}")
    .then()
        .statusCode(200)
        .body("name", equalTo("Evelyn Sparrow"))
        .body("patronus", not(emptyOrNullString()));
}

Worth pointing out: pathParam and queryParam do different jobs, and mixing them up is a classic beginner trip-up. Path params fill in placeholders in the URL (/students/{id}), query params get appended after a ?.

Testing what happens when things go wrong

A test suite that only checks the happy path isn't testing much. Let's hit a house ID that doesn't exist:

@Test
void unknownHouseReturns404() {
    given()
        .pathParam("id", 99)
    .when()
        .get("/houses/{id}")
    .then()
        .statusCode(404)
        .body("error", equalTo("Not Found"))
        .body("message", containsString("No house with id 99"));
}

This matters more than it looks. A lot of "working" API test suites out there only ever prove the API says yes — they never prove it says no correctly, which is usually where the real bugs hide.

Testing an authenticated endpoint

Some endpoints, like enrolling a new student, require a Bearer token. This API accepts a couple of fixed test tokens (qa-admin-token and qa-viewer-token) specifically so you can practice auth flows without registering anywhere. First, let's confirm it actually rejects unauthenticated requests:

@Test
void enrollingWithoutTokenIsRejected() {
    String body = "{ \"name\": \"Rowan Ashby\", \"houseId\": 1, \"year\": 1 }";

    given()
        .contentType("application/json")
        .body(body)
    .when()
        .post("/students")
    .then()
        .statusCode(401)
        .body("error", equalTo("Unauthorized"));
}

Now with the token attached:

@Test
void enrollStudentWithValidToken() {
    String body = "{ \"name\": \"Rowan Ashby\", \"houseId\": 1, \"year\": 1 }";

    given()
        .header("Authorization", "Bearer qa-admin-token")
        .contentType("application/json")
        .body(body)
    .when()
        .post("/students")
    .then()
        .statusCode(201)
        .body("name", equalTo("Rowan Ashby"))
        .body("houseId", equalTo(1));
}

That pair of tests, rejected-then-accepted, is the pattern you'll reuse constantly once you move past tutorials and start testing real auth-protected APIs at work.

Cleaning it up with a request specification

Once you've got more than a couple of tests, repeating the base URI and headers everywhere gets old fast. Rest Assured's RequestSpecification fixes that:

import io.restassured.specification.RequestSpecification;
import io.restassured.builder.RequestSpecBuilder;

public class BaseTest {
    protected static RequestSpecification spec;

    static {
        spec = new RequestSpecBuilder()
            .setBaseUri("https://funapi.dev/api/wizarding/v1")
            .setContentType("application/json")
            .build();
    }
}

Then any test class extending BaseTest can just do given().spec(spec).when()... instead of repeating the setup every time. It's a small change, but it's usually the first refactor every real Rest Assured suite ends up needing.

Where to go from here

You've now covered the core moves: GET and POST requests, status code and JSON body assertions, query and path parameters, error responses, and a Bearer-token-protected endpoint. That's genuinely most of what you'll use day to day.

If you want more to practice on, there's a random spell endpoint (GET /spells/random) that's a nice one for getting comfortable asserting on non-deterministic responses, and the sorting hat endpoint (POST /sorting-hat) is good for practicing POST requests that don't need a body at all. Beyond this one API, the same playground has things like pagination with cursors, OAuth flows, and endpoints that deliberately return every status code from 400 to 503, if you want to keep leveling up your API testing without switching tools.

Either way, the fastest way to actually learn Rest Assured is what you just did: stop reading, open an IDE, and start asserting on something.