root access

$ cat job-board-api/part-19.md

Building a Job Board API, Part 19: Who Can Do What, and What the API Really Does

I’m sharing one of my projects here from the beginning, step by step. It’s a Job Board API built with Django, Django REST Framework, PostgreSQL and Docker Compose, with S3 and SQS (through LocalStack), Redis, and a background worker.

I’m a junior engineer looking for my first role in DevOps, SRE or Cloud. That’s why I build projects like this and write about them in public. It shows how I think, and writing it down helps me really understand it.

In Part 18 I set up the tests and wrote the first unit tests. This part answers two questions:

  • Who can do what? Permission tests: unit tests for each permission class, and a matrix that tries every protected action as every kind of user.
  • What does each endpoint really do? API tests for signup, login, jobs, filters and applications.

On the way, one fixture made the whole suite 29 times faster.

Part 1: testing the permission classes directly

I have four permission classes from Part 5: IsVerifiedCompany, IsCandidate, IsJobOwner and IsApplicantOwner. They only read request.user, so I don’t need a full HTTP request to test them:

from types import SimpleNamespace


def req(user):
    return SimpleNamespace(user=user)

SimpleNamespace(user=...) is a tiny object with one attribute. That’s all the classes need.

def test_is_verified_company(make_company, make_candidate):
    permission = IsVerifiedCompany()

    assert not permission.has_permission(req(AnonymousUser()), None)
    assert not permission.has_permission(req(make_candidate().user), None)
    assert permission.message == "Only company accounts can do this."
    assert permission.has_permission(req(make_company("acme").user), None)

AnonymousUser is what Django puts on request.user when nobody is logged in. Its is_authenticated is False, and it has no is_company or is_candidate attribute.

The anonymous case works only because the class checks not user.is_authenticated first. Python’s or stops there, so the missing is_company is never read. If someone reordered those checks, this test would crash with AttributeError.

None for the view, because the class doesn’t use it.

A message that explains why

IsVerifiedCompany changes its own message to explain why access was denied. The tests check both cases, an unverified company and an “orphan” (a company-role user with no Company row), and they both get “Your company account is not verified.”

The orphan works because of getattr(user, "company", None). Django’s “related object does not exist” error is a subclass of AttributeError, which getattr with a default catches.

The last line is the important one:

assert IsVerifiedCompany.message == "Only company accounts can do this."

The message is changed on the instance, not the class. DRF creates a new permission object for every request. If the class default changed, one denied request could change the message for the next user.

The other three classes

IsCandidate: anonymous, a company and a candidate role without a profile are all denied. The role alone isn’t enough, because applying needs a candidate_profile. IsJobOwner: tested with both a Job and an Application. It uses obj.job for applications, which is how one class protects both job updates and status changes. Another company, a candidate and anonymous are denied. IsApplicantOwner: two kinds of owner may read an application: the applicant and the job’s company. Another candidate and another company may not.

has_object_permission(request, view, obj) is the object-level check. Remember this one: it matters in the next section.

Part 2: the matrix through the real endpoints

Unit tests prove each class is correct. But a class can be correct and still wired wrong, for example attached to the wrong action in get_permissions(). So the second set of tests goes through the real endpoints.

One small world with every kind of user

@pytest.fixture
def world(make_company, make_candidate, make_job, make_application):
    acme = make_company("acme", verified=True)
    globex = make_company("globex", verified=True)
    initech = make_company("initech", verified=False)
    sam = make_candidate("sam", skills=["aws"])
    riya = make_candidate("riya")
    job = make_job(acme, required_skills=["aws"])
    application = make_application(job, sam, resume="resume/job-test/cv.pdf")
    users = {
        "anon": None,
        "acme": acme.user,
        "globex": globex.user,
        "initech": initech.user,
        "sam": sam.user,
        "riya": riya.user,
    }
    return SimpleNamespace(job=job, application=application, users=users)

Six actors:

  • acme, the job’s owner;
  • globex, another verified company;
  • initech, an unverified company;
  • sam, the applicant;
  • riya, another candidate;
  • anon, nobody.

The names match my manual curl checks from earlier phases. And resume= is only a file name: no upload happens. Creating a presigned URL is a local signing calculation, so the resume endpoint works without S3.

@pytest.fixture
def client_for(world):
    def _client(who):
        client = APIClient()
        if world.users[who] is not None:
            client.force_authenticate(user=world.users[who])
        return client

    return _client

APIClient is DRF’s test client. It understands format="json" and "multipart".

force_authenticate(user=...) skips JWT completely and logs the request in as that user. The matrix is about who the user is, not about tokens. The real token flow has its own tests later in this article.

For anon, there’s no authentication at all.

The matrix tests

Each test tries one action as several users, with parametrize:

@pytest.mark.parametrize(
    ("who", "expected"),
    [("anon", 401), ("sam", 403), ("initech", 403), ("acme", 201), ("globex", 201)],
)
def test_only_verified_companies_post_jobs(client_for, who, expected):
    response = client_for(who).post("/api/jobs/", NEW_JOB, format="json")

    assert response.status_code == expected

A candidate is the wrong role, and initech isn’t verified.

Two verified companies succeed with 201 Created, so the rule really is “verified companies”, not “only acme”.

A second test checks the 403 body: initech gets “Your company account is not verified.” and sam gets “Only company accounts can do this.”. The response tells the user what to do.

401 or 403?

401 means “who are you?”: no credentials, or bad ones.

403 means “I know who you are, and you can’t do this”.

Anonymous users get 401, not 403. DRF returns 401 when the request isn’t authenticated and the authenticator can send a WWW-Authenticate header. The JWT authenticator does (Bearer realm="api").

Denied means nothing changed

This is the most important idea in the matrix:

@pytest.mark.parametrize(
    ("who", "expected"),
    [("anon", 401), ("sam", 403), ("globex", 403), ("acme", 200)],
)
def test_only_the_owner_updates_a_job(client_for, world, who, expected):
    response = client_for(who).patch(
        f"/api/jobs/{world.job.id}/", {"title": "Changed"}, format="json"
    )
    world.job.refresh_from_db()

    assert response.status_code == expected
    assert (world.job.title == "Changed") == (expected == 200)

refresh_from_db() reloads the row from the database. The last line says: the title changed if and only if the request was allowed.

Why check the data and not only the status code? Because a view could save first and check permissions later. It would return 403 and still have changed the data. A status check alone would pass. This line catches it.

The same idea protects status changes. The applicant can’t change their own status, which is a real risk: a candidate moving themselves to “offered”. After the request, the test reloads the application and checks the status is still submitted unless the job’s owner did it.

The other rows

Reading jobs needs any login, and nothing more. Even an unverified company may browse.

The applicants list contains other people’s names and match scores. Only the job’s owner gets 200.

Applying: sam gets 400 on purpose. An empty body passes the permission check and fails validation. The 400 proves he got through the permission. A real successful apply needs an S3 upload, which is in the next article.

Reading an application and the resume link (a working download link to someone’s CV, the most sensitive endpoint): only the applicant and the job’s owner.

Non-owners get 403, not 404. The object is found first, then the permission check denies it. That reveals the ID exists. It’s an accepted trade-off from Part 5, because IDs aren’t secret here.

Here is the whole matrix in one picture:

Every protected action, tried as every kind of user

Two fixtures that apply to every test

The matrix needed two fixtures marked autouse=True. An autouse fixture applies to every test, without being named as an argument.

A fresh in-memory cache for each test

@pytest.fixture(autouse=True)
def local_cache(settings):
    settings.CACHES = {
        "default": {"BACKEND": "django.core.cache.backends.locmem.LocMemCache"}
    }
    from django.core.cache import cache

    cache.clear()

settings is pytest-django’s fixture for changing settings in one test. The old value comes back automatically afterwards.

Why replace Redis? Two reasons:

  • Isolation. Inside a test, nothing is ever committed. So my cache invalidation from Part 9, which runs on commit, never runs. A cached job list from one test would be served to the next.
  • No dependency. The suite doesn’t need Redis running. I proved it: with Redis stopped, 80 passed.

Assigning CACHES fires Django’s setting_changed signal, which resets the cache connections, so cache really points at the new backend.

cache.clear(): the in-memory cache lives as long as the process, so clearing it gives each test an empty cache.

The 29x speedup

After I added the matrix, the suite suddenly took 27.13 seconds. It had been about 2.7 seconds. That’s 10 times slower.

I didn’t guess. I measured with --durations=3, which shows the slowest test phases. All of them were the setup phase of matrix tests, at 0.62 to 0.63 seconds each.

The cause: the world fixture creates 5 users per test. create_user hashes each password with PBKDF2, and Django makes PBKDF2 slow on purpose, with hundreds of thousands of iterations, so stolen password hashes are hard to crack. About 160 slow hashes added up to 27 seconds.

The fix:

@pytest.fixture(autouse=True)
def fast_password_hashing(settings):
    settings.PASSWORD_HASHERS = ["django.contrib.auth.hashers.MD5PasswordHasher"]

MD5 is fast, and completely unsafe for real passwords. That’s fine here, because test users live for one test.

The result: the same 80 tests in 0.92 seconds, about 29 times faster. I switched the fixture off and on with sed to measure both.

Production is unchanged. grep PASSWORD_HASHERS finds it only in conftest.py. Production keeps PBKDF2.

Why does speed matter this much? A 27-second suite is one that people stop running. A 1-second suite runs after every change.

Part 3: what each endpoint really does

The matrix proved who gets in. The API tests prove what happens when they do. I added one more factory fixture, api_as(user), which returns an APIClient logged in as any user, or anonymous with api_as().

Registration

STRONG = "s3cure-pass-2026"
COMPANY = {"username": "newco", "email": "Hello@NewCo.test", "password": STRONG, "company_name": "NewCo"}

STRONG passes all four of Django’s password validators. The email has capitals on purpose, to test lower-casing.

def test_company_registration_creates_user_and_unverified_company(db):
    response = post("/api/auth/register/company/", COMPANY)
    body = response.json()

    assert response.status_code == 201
    assert body["role"] == "company"
    assert body["email"] == "hello@newco.test"
    assert "password" not in body
    company = Company.objects.get(user__username="newco")
    assert company.name == "NewCo"
    assert company.is_verified is False

The response is checked against the database, not just itself.

"password" not in body: the field is write_only, so signup can’t echo the password back.

is_verified is False: new companies can’t post jobs until they’re verified. Self-registration can’t skip that step.

The other registration tests:

  • The client can’t choose its role or staff flag. Sending "role": "company", "is_staff": True to the candidate endpoint still creates a normal candidate. This attack is called mass assignment. The serializer has no role or is_staff field, so DRF ignores unknown keys, and the role comes from which endpoint was called.
  • The password is hashed: the stored value isn’t the plain password, and the plain password still verifies with check_password.
  • Duplicates are rejected case-insensitively: SAM and SAM@Example.test both clash with an existing sam. The error key shows which check fired.
  • Weak passwords are rejected, one example per validator (12345678, password, short), and no user is created.

Registration is atomic

def test_company_registration_is_atomic(db, monkeypatch):
    def boom(**kwargs):
        raise RuntimeError("database hiccup")

    monkeypatch.setattr(Company.objects, "create", boom)

    with pytest.raises(RuntimeError):
        post("/api/auth/register/company/", COMPANY)

    assert not User.objects.filter(username="newco").exists()

monkeypatch.setattr(obj, name, value) replaces something for this test only, then puts it back. Here, creating the company fails after the user was already created.

What it proves: @transaction.atomic rolls back the user too. Without it, there would be a company-role user with no company, and every company endpoint would treat them as “not verified” forever.

pytest.raises around an API call works because Django’s test client re-raises an unhandled exception from a view, instead of returning a 500.

One more registration test sends Authorization: Bearer garbage. It still gets 201, because the signup views set authentication_classes = []. Otherwise, a browser with an expired token from an old session could never sign up again.

The real JWT flow

The matrix used force_authenticate. These tests use real tokens:

def bearer(token):
    client = APIClient()
    client.credentials(HTTP_AUTHORIZATION=f"Bearer {token}")
    return client

Login returns exactly access and refresh, nothing extra.

The access token opens protected endpoints. The full chain: credentials, then token, then endpoint.

A wrong password is 401, and a garbage token is 401, not a 500.

Refresh gives a working access token, checked by using it.

A refresh token is not an access token:

def test_refresh_token_is_not_an_access_token(make_candidate):
    make_candidate("sam")
    refresh = login("sam").json()["refresh"]

    assert bearer(refresh).get("/api/jobs/").status_code == 401

A refresh token lives for 1 day, and an access token for 15 minutes. If a refresh token worked as an access token, the short lifetime would mean nothing. SimpleJWT stores a token_type inside each token and rejects the wrong kind.

Jobs: creating and updating

def test_create_normalises_skills_and_takes_company_from_the_user(api_as, acme, make_company):
    make_company("globex")
    response = api_as(acme.user).post(
        "/api/jobs/",
        {**NEW_JOB, "required_skills": [" Python ", "AWS", "aws"], "company": "Globex"},
        format="json",
    )
    body = response.json()

    assert response.status_code == 201
    assert body["required_skills"] == ["python", "aws"]
    assert body["company"] == "Acme"
    assert Job.objects.get(id=body["id"]).company == acme

Skill normalising, step by step: DRF trims " Python " first, then my validator lower-cases, then dict.fromkeys removes the duplicate and keeps the first-seen order. So the result is exactly ["python", "aws"].

"company": "Globex" is ignored. company is read-only, and the view sets it from the logged-in user. A company can’t post jobs as someone else.

Updates go through the same validator. If only create normalised, a later edit could bring back "Go" and break the filters, which search in lower case.

I had marked one expectation as uncertain before running it, and it turned out correct. A blank skill " " is rejected with 400, not silently dropped. DRF trims " " to "" and rejects it as blank before my validator even runs. So the blank-skill filter inside my validator never sees blanks from the API. It still protects the model if something else writes skills.

Other job tests: missing fields are all reported at once ({"title", "description", "location"} <= set(...), where <= on sets means “is a subset”), an invalid job_type is a 400, and closed jobs are hidden from the list but not from the detail page, so old links and the owner’s applicant pages keep working.

Filters, search and ordering

The board fixture creates four jobs, built so that every filter separates them: different companies, types, locations and skills. A fourth, closed job matches aws and acme, so every test also proves it stays hidden.

@pytest.mark.parametrize(
    ("params", "expected"),
    [
        ({}, ["Data Analyst", "Junior DevOps Engineer", "SRE Intern"]),
        ({"job_type": "contract"}, ["Data Analyst"]),
        ({"location": "vancouver"}, ["Junior DevOps Engineer"]),
        ({"skills": "python"}, ["Data Analyst", "SRE Intern"]),
        ({"skills": " AWS , Go "}, ["Junior DevOps Engineer"]),
        ({"skills": "python,terraform"}, ["Data Analyst", "Junior DevOps Engineer", "SRE Intern"]),
        ({"search": "acme"}, ["Junior DevOps Engineer", "SRE Intern"]),
        ({"search": "analyst"}, ["Data Analyst"]),
        ({"job_type": "contract", "skills": "python"}, ["Data Analyst"]),
    ],
)
def test_filters_and_search(api_as, board, params, expected):
    response = api_as(board.user).get("/api/jobs/", params)

    assert response.status_code == 200
    assert sorted(titles(response)) == expected

One row per rule:

  • location is a case-insensitive substring;
  • skills is normalised the same way as stored skills;
  • several skills match any of them (PostgreSQL’s array overlap), not all;
  • search covers the title, the description and the company name;
  • several filters combine with AND.

sorted(...) is used because these tests are about which jobs, not their order. An invalid filter value like job_type=forever returns 400 with an explanation, instead of silently returning nothing.

The ordering test does not sort, because the order is the thing being tested. The default is newest first. And ordering=password is ignored: only fields in ordering_fields are allowed. Sorting by an arbitrary field would let clients sort by data they can’t see, and with enough requests, work out hidden values.

The pagination test creates 21 jobs, the smallest number that needs a second page (PAGE_SIZE is 20). Page 1 has 20 results and a next link, and page 2 has 1 result and next is None.

Applications: every rejection before any upload

The application tests check that each bad request is rejected before anything is uploaded to S3: no resume (400), a wrong file type (400), a closed job (“This job is no longer accepting applications.”), an unknown job (400, not 404), and a second application to the same job (“You have already applied for this job.”, with still only 1 application in the database).

The reading tests check the response shape. match_score is 50 (1 of 2 required skills), has_resume is True, and "resume" not in body: the storage path never leaves the server. The only way to get the file is the permission-checked, short-lived link, and its test checks it uses the public endpoint localhost:4566, not the internal localstack:4566. That was the bug I fixed in Part 7.

Status changes: publish once, only on a real change

def test_status_change_publishes_once_and_only_on_change(api_as, setup, make_application, monkeypatch):
    acme, sam, job = setup
    application = make_application(job, sam)
    calls = []
    monkeypatch.setattr("jobs.views.publish_status_changed", lambda app, old: calls.append((app.id, old)))
    client = api_as(acme.user)
    url = f"/api/applications/{application.id}/status/"

    first = client.patch(url, {"status": "reviewing"}, format="json")
    second = client.patch(url, {"status": "reviewing"}, format="json")

    assert first.status_code == second.status_code == 200
    assert first.json()["status"] == "reviewing"
    assert "match_score" in first.json()
    assert calls == [(application.id, "submitted")]

Patch the name where it’s used. views.py does from .events import publish_status_changed, which copies the reference into jobs.views. Patching jobs.events.publish_status_changed would leave the view calling the original. The same rule caught me in Phase 3, with the worker.

The lambda records calls instead of sending anything. This test is about when the view publishes, not how. The “how” is in the next article.

Two identical PATCHes: the first publishes once, with the old status. The second changes nothing, so it publishes nothing. That’s the same rule as the “no email after a 200” surprise in Part 14.

An empty body and an unknown status like hired both return 400 with DRF’s exact messages. The empty body used to return 200 and do nothing, which was a bug back in Phase 2. This test makes sure it stays fixed.

Problems I hit

  1. 14 errors from my own fixture
    The first run of the job tests gave 14 setup errors:
    TypeError: QuerySet.create() got multiple values for keyword argument 'location'
    The cause was my make_job fixture from Part 18. At first it passed location="Vancouver" hard-coded, and **fields. The board fixture was the first to pass its own location=, so location arrived twice.
    The fix: location="Vancouver" became a parameter with a default. A parameter with a default can be overridden. A hard-coded argument next to **fields can’t.
  2. A typo that worked
    While reading the serializer, I found def validate_email(delf, value). It worked, because Python doesn’t care what the first parameter is called. I fixed it to self anyway.
  3. Output that scrolled away
    The first output was too long to read. I re-ran with -q and 2>&1 | tail -n 40.

Breaking the code on purpose

As in Part 18, I broke the code to prove the tests can catch it.

The permissions: I removed the owner check from the views:

return [IsAuthenticated(), IsJobOwner()]    # the real code
return [IsAuthenticated()]                  # the deliberate bug

The result: 7 failed, 35 passed. The 7 were exactly every non-owner case of the three actions IsJobOwner protects: job update, the applicants list and status change. They all got 200 and changed data. The failure output even showed job=<Job: Changed (Acme)>: non-owners had really renamed Acme’s job. That’s the “denied means nothing changed” check doing its job. The anonymous cases still got 401, because IsAuthenticated was still there.

This also showed something important about has_object_permission: it only runs when the view calls get_object(). So IsJobOwner protects nothing on a list or create action.

The skills: I removed .lower() from the skills validator. Exactly 2 tests failed: the two normalisation tests, with ['Python', 'AWS', 'aws'] and ['Go', 'GO'] kept as typed. Everything else passed.

After each check, git checkout restored the code, and all tests passed again.

The numbers: 42 permission tests (permissions.py at 100%) and 51 API tests (serializers.py at 99%). The total coverage went to 78%.

Why I chose this way

  • Unit tests and an endpoint matrix. A class can be right but wired wrong in get_permissions. Only both together catch both kinds of mistakes.
  • One world per test. Each test is independent. Shared module-level data would let tests affect each other.
  • force_authenticate in the matrix. It separates who you are from how you logged in. The real tokens have their own tests.
  • MD5 in tests only. 29 times faster, production unaffected.
  • Record calls instead of mocking SQS in the view test. It tests the view’s decision, not the transport.
  • Exact user-facing messages. They’re part of the API’s contract, not just the status codes.

What I learned

  • Test the classes and the wiring. Unit tests alone miss a class attached to the wrong action.
  • has_object_permission only runs through get_object().
  • 401 means “who are you?”, 403 means “you can’t”.
  • A denied write must change nothing. Check the data, not only the status.
  • Measure before optimising. --durations pointed straight at password hashing.
  • Mass assignment is blocked by not declaring fields, and a test proves it.
  • A refresh token must not work as an access token.
  • Patch a name where it’s used, not where it’s defined.
  • A mutation that fails exactly the expected tests is the best proof your tests are aimed right.

What comes next

So far, no test has talked to S3 or SQS. The next article is about faking AWS with a library called moto, testing the worker’s main loop with a fake queue, and testing what happens when Redis fails. Some of those tests document known gaps instead of hiding them.

$ ls -t root-access/ | head -3

Building a Job Board API, Part 18: Tests in a Container job-board-api · 18/19 18 min Building a Job Board API, Part 17: A Production Image with gunicorn job-board-api · 17/19 16 min Building a Job Board API, Part 16: All Config from Environment Variables job-board-api · 16/19 19 min

Leave a comment

Your email address will not be published. Required fields are marked *