API TESTING

Testing API Responses That Change Shape by User Role

One of the sneakiest bugs I see in real-world API testing is the shape-shift: an endpoint returns one JSON structure for an admin, a different one for a regular user, and something else entirely for a guest. The contract isn't broken — the API is doing exactly what it was designed to do — but if your test suite only ever authenticates as one role, you're covering one shape and silently ignoring the rest. That gap lives quietly in your pipeline until a customer hits it in production.

This isn't a rare edge case. Role-differentiated responses show up constantly in product APIs: a /me endpoint that includes a billing_info block for account owners but omits it entirely for read-only members; a /orders response that exposes internal cost fields for warehouse staff but strips them for customers; a GraphQL query that resolves extra fields based on permission scopes. The field isn't missing by accident — it's conditionally present by design. That design decision still needs a test.

In this article I'll walk through how I structure tests for role-variant responses: how to model the expected shapes per role, how to assert the right fields are present and the wrong ones are absent, and how to keep those tests maintainable as roles multiply. Everything here applies whether you're using pytest with requests, Behave for BDD-style scenarios, or any other Python-based stack.

Build an API Automation Framework With Node.js

Learn Node.js, Cucumber, GitHub Copilot, APIs, CI/CD, and modern automation by building a complete framework.

Learn more

Mapping the Response Contract Per Role Before You Write a Single Test

The first mistake teams make is jumping straight to code without mapping what each role is actually supposed to receive. I always start with a simple matrix — role on one axis, fields on the other — and mark each cell as "always present," "conditionally present," or "must be absent." It sounds like overhead, but it takes fifteen minutes and it becomes the specification your tests enforce.

Here's a minimal example. Say your GET /users/{id} endpoint returns a user profile. The expected shapes might look like this:

  • Admin: id, email, role, internal_notes, created_at, last_login_ip
  • Account Owner: id, email, role, created_at
  • Read-Only Member: id, email

Notice that internal_notes and last_login_ip are admin-only. They must be absent from the other two responses — not null, not empty string, absent. That distinction matters enormously. An API that returns "internal_notes": null to a regular user is leaking a field name, which can expose implementation details or invite probing. Catching missing or unexpected fields before prod does means asserting both presence and absence explicitly, not just checking that the response parses without error.

Once you have the matrix, translate it into a data structure your tests can consume. In pytest, a parametrize-friendly format works well:

ROLE_SHAPES = {
    "admin": {
        "required": ["id", "email", "role", "internal_notes", "created_at", "last_login_ip"],
        "forbidden": [],
    },
    "owner": {
        "required": ["id", "email", "role", "created_at"],
        "forbidden": ["internal_notes", "last_login_ip"],
    },
    "member": {
        "required": ["id", "email"],
        "forbidden": ["internal_notes", "last_login_ip", "role", "created_at"],
    },
}

This dictionary is your living spec. When the product adds a new field or a new role, you update this one structure and every test that drives from it automatically picks up the change. That's the kind of maintainability that actually survives a real project.

Writing Assertions That Verify Both Field Presence and Field Absence by Role

Once you have the shape map, the assertion logic is straightforward — but there are a few patterns worth being deliberate about. The core idea is to write two separate assertion passes for every role: one that confirms every required field exists and has a non-null value (unless null is explicitly valid), and one that confirms every forbidden field is completely absent from the response body.

Here's a pytest example that parametrizes across roles and uses a shared helper:

import pytest
import requests

BASE_URL = "https://api.example.com"

# Tokens keyed by role — loaded from env or fixtures in practice
AUTH_TOKENS = {
    "admin": "Bearer token-admin",
    "owner": "Bearer token-owner",
    "member": "Bearer token-member",
}

ROLE_SHAPES = { ... }  # as defined above

def assert_shape(body: dict, role: str):
    spec = ROLE_SHAPES[role]
    for field in spec["required"]:
        assert field in body, f"[{role}] Expected field '{field}' missing from response"
    for field in spec["forbidden"]:
        assert field not in body, f"[{role}] Forbidden field '{field}' present in response"

@pytest.mark.parametrize("role", ["admin", "owner", "member"])
def test_user_profile_shape_by_role(role):
    headers = {"Authorization": AUTH_TOKENS[role]}
    response = requests.get(f"{BASE_URL}/users/42", headers=headers)
    assert response.status_code == 200
    assert_shape(response.json(), role)

A few things worth calling out in this pattern. First, the token management: in a real suite you'd pull these from environment variables or a pytest fixture that handles token refresh — hardcoding them here is just for clarity. Second, the user ID 42 should be a fixture-managed resource that all three roles have valid access to; if the member role gets a 403 instead of a 200, that's a different (and legitimate) test, but it's not the shape test. Keep the concerns separate.

The same pattern translates cleanly to Behave if you prefer BDD-style scenarios. The advantage there is that your Gherkin steps read as business rules: "Given I am authenticated as a read-only member, when I request a user profile, then the response must not include internal_notes." That kind of scenario doubles as documentation of access-control intent — which matters when your tests are serving as the authoritative record of business rules for your team.

One more thing to assert that teams often skip: the type of present fields, not just their existence. An admin endpoint that returns "last_login_ip": 0 instead of a valid IP string has a bug, even though the field is technically "present." Add a type-check layer to your assert_shape helper once your shape map matures enough to include expected types.

Handling Role-Based Shape Changes in GraphQL, Nested Objects, and CI

REST endpoints with flat response bodies are the easy case. The patterns above get more interesting — and more important — when you're dealing with GraphQL, deeply nested objects, or responses that vary not just in which fields appear but in which nested sub-objects are included at all.

In GraphQL, the client nominally controls the shape by specifying fields in the query. But the server still enforces permissions — a field in your query might resolve to null or be omitted entirely if the caller lacks the right scope. That means your test queries need to ask for the full superset of fields, and then your assertions need to check what came back versus what should have come back for that role. Don't write separate queries per role; write one maximal query and assert the shape of the result per role. Otherwise you're hiding the gap rather than testing it.

For nested objects, extend your shape map to handle dot-notation paths or nested dicts:

ROLE_SHAPES = {
    "admin": {
        "required": ["id", "email", "billing.card_last4", "billing.plan"],
        "forbidden": [],
    },
    "member": {
        "required": ["id", "email"],
        "forbidden": ["billing"],
    },
}

def get_nested(body: dict, path: str):
    keys = path.split(".")
    node = body
    for key in keys:
        if not isinstance(node, dict) or key not in node:
            return None, False
    node = node[key]
    return node, True

def assert_shape(body: dict, role: str):
    spec = ROLE_SHAPES[role]
    for path in spec["required"]:
        _, found = get_nested(body, path)
        assert found, f"[{role}] Required nested field '{path}' missing"
    for path in spec["forbidden"]:
        _, found = get_nested(body, path)
        assert not found, f"[{role}] Forbidden nested field '{path}' present"

Finally, think about where these tests live in your pipeline. Role-based shape tests are contract tests — they're fast, they don't depend on complex state, and they should run on every pull request. Placing them early in your CI/CD pipeline means a developer who accidentally exposes an admin field to a member role gets immediate feedback, not a security review comment three days later.

Also watch for the access-control cousin of this problem: an endpoint that returns a 403 for one role when it should return a 200 with a reduced-shape response. That's a design decision, not a bug — but your tests need to encode which behavior is correct for which role. I've seen teams test the happy path for admin only, assume other roles get 403s, and then discover in prod that members were actually getting 200s with full admin payloads. The shape test catches that. The status-code-only test doesn't. If you want to go deeper on the error-response side of this, testing what happens beyond the happy path is the natural complement to everything covered here.