REST API Test Design Complete Guide | pytest × requests — Happy Path · Error Cases · Auth Explained

REST API testing has one core difficulty: knowing where to stop. What actually needs to be tested?

QA engineers new to API testing often wrestle with questions like:

• Is testing the happy path enough?
• How far do I need to go with auth and error cases?
• How do I structure my API test cases?

This article answers all of that. We cover the 4-axis REST API test design framework — happy path, error cases, authentication, and boundary values — with working pytest × requests implementation code throughout.

API tests are generally faster and more stable than E2E tests, making them an excellent foundation for CI/CD pipelines. Structuring your test design around the 4 axes in this article leads to fewer bugs slipping through and significantly easier test maintenance.

REST API Testing vs E2E Testing — What’s the Difference?

REST API testing sends HTTP requests directly to API endpoints and validates that responses match expectations — no browser required. This makes it significantly faster than E2E testing.

REST API Test Design — The 4-Axis Framework

Structured API test design uses four axes. Cover all four and you get comprehensive, gap-free test coverage.

STEP 1: Environment Setup — pytest × requests

pip install requests pytest pytest-html

Project structure:

api-test-project/
├── tests/
│   ├── conftest.py         # base_url, auth tokens, shared fixtures
│   ├── utils.py            # safe_json helper
│   ├── test_users.py       # user API tests
│   ├── test_posts.py       # post API tests
│   └── test_auth.py        # auth API tests
├── requirements.txt
└── pytest.ini

conftest.py

# tests/conftest.py
import pytest
import requests

@pytest.fixture(scope="session")
def base_url():
    """Base URL as a fixture — easy to swap per environment."""
    # ※ Sample URL. Replace with your actual API.
    return "https://jsonplaceholder.typicode.com"

@pytest.fixture(scope="session")
def auth_headers():
    """Auth headers as a fixture."""
    return {
        "Authorization": "Bearer YOUR_TOKEN_HERE",
        "Content-Type": "application/json"
    }

class TimeoutSession(requests.Session):
    """Session with a default timeout.
    requests.Session has no built-in default timeout — this wrapper adds one.
    """
    def request(self, *args, **kwargs):
        # connect timeout=3s / read timeout=10s
        # Pass timeout=None to override per-request
        kwargs.setdefault("timeout", (3, 10))
        return super().request(*args, **kwargs)

@pytest.fixture(scope="session")
def api_session():
    """Shared Session fixture with default timeout.
    Using Session reuses HTTP connections for better performance.
    """
    session = TimeoutSession()
    session.headers.update({"Content-Type": "application/json"})
    yield session
    session.close()

tests/utils.py — safe_json helper

# tests/utils.py
import pytest

def safe_json(response):
    """Safely parse JSON. Fails test with a clear message on parse error."""
    try:
        return response.json()
    except ValueError:
        # JSONDecodeError is a subclass of ValueError — one except covers both
        pytest.fail("Response is not valid JSON")

# Import in test files:
from tests.utils import safe_json

# raise_for_status() raises an exception on 4xx/5xx responses.
# Use it in happy path tests to fail fast on unexpected errors.
# Do NOT use it in error case tests — you want to assert the status code directly.

# Happy path (raise_for_status is fine here):
response = api_session.get(f"{base_url}/users/1")
response.raise_for_status()
data = safe_json(response)

# Error case test (do NOT use raise_for_status):
response = api_session.get(f"{base_url}/users/99999")
assert response.status_code == 404  # raise_for_status() would throw here

STEP 2: Happy Path Test Design — Validating by HTTP Method

Happy path tests verify both the expected status code and the response body. Both matter.

GET requests

# tests/test_users.py
import pytest
import requests
from tests.utils import safe_json

class TestGetUser:

    def test_get_user_returns_200(self, base_url, api_session):
        """Happy path: GET user returns 200."""
        # TimeoutSession applies timeout=(3, 10) automatically — no need to specify
        response = api_session.get(f"{base_url}/users/1")
        assert response.status_code == 200

    def test_get_user_returns_expected_fields(self, base_url, api_session):
        """Happy path: Response includes required fields."""
        response = api_session.get(f"{base_url}/users/1")
        data = safe_json(response)

        assert "id" in data
        assert "name" in data
        assert "email" in data

    def test_get_user_id_matches_request(self, base_url, api_session):
        """Happy path: Returned user ID matches the requested ID."""
        user_id = 1
        response = api_session.get(f"{base_url}/users/{user_id}")
        data = safe_json(response)

        assert data["id"] == user_id

    def test_get_users_list_returns_array(self, base_url, api_session):
        """Happy path: User list is returned as an array."""
        response = api_session.get(f"{base_url}/users")
        data = safe_json(response)

        assert isinstance(data, list)
        assert len(data) > 0

    @pytest.mark.performance  # Isolate from CI — register in pytest.ini: markers = performance: ...
    def test_response_time_is_acceptable(self, base_url, api_session):
        """Happy path: Response arrives within 2 seconds."""
        response = api_session.get(f"{base_url}/users/1")

        # response.elapsed covers the full HTTP round-trip:
        # DNS resolution, TCP connection, TLS handshake, server response time
        # It is NOT a measure of application processing time alone.
        # network jitter makes this flaky in CI — run as "pytest -m 'not performance'" to exclude
        assert response.elapsed.total_seconds() < 2.0

    def test_response_is_valid_json(self, base_url, api_session):
        """Happy path: Response is valid JSON."""
        response = api_session.get(f"{base_url}/users/1")

        # If an HTML error page is returned, response.json() throws JSONDecodeError.
        # Check Content-Type first for a clearer failure message.
        # RFC 7807 error APIs may return application/problem+json
        content_type = response.headers.get("Content-Type", "")
        assert (
            "application/json" in content_type
            or "application/problem+json" in content_type
        )

        data = safe_json(response)
        assert "id" in data

POST requests

class TestCreatePost:

    def test_create_post_returns_201(self, base_url, api_session):
        """Happy path: POST returns 201 Created."""
        payload = {"title": "Test Post", "body": "Test body", "userId": 1}
        response = api_session.post(f"{base_url}/posts", json=payload)

        assert response.status_code == 201

    def test_create_post_returns_created_data(self, base_url, api_session):
        """Happy path: Response includes the created post data."""
        payload = {"title": "Title", "body": "Body", "userId": 1}
        response = api_session.post(f"{base_url}/posts", json=payload)
        data = safe_json(response)

        assert data["title"] == payload["title"]
        assert data["body"] == payload["body"]
        assert "id" in data  # New ID assigned by the server

STEP 3: Error Case Test Design — Covering Error Patterns

Error case tests verify that invalid requests return appropriate error responses. pytest's parametrize makes covering multiple patterns efficient.

class TestErrorHandling:

    def test_get_nonexistent_user_returns_404(self, base_url, api_session):
        """Error case: Non-existent user ID returns 404."""
        response = api_session.get(f"{base_url}/users/99999")

        assert response.status_code == 404

    @pytest.mark.parametrize("invalid_id", [
        "abc",      # string
        "!@#",      # symbols
        "-1",       # negative
        "0",        # zero
        "9" * 20,   # extremely long number
    ])
    def test_get_user_with_invalid_id(self, base_url, api_session, invalid_id):
        """Error case: Invalid IDs return 400 or 404."""
        response = api_session.get(f"{base_url}/users/{invalid_id}")

        # The specific code (400 vs 404) depends on your API spec.
        # Ideally, pin to one value based on the spec. Multiple-allowed is a stopgap.
        assert response.status_code in [400, 404]

    @pytest.mark.parametrize("missing_field, payload", [
        ("title",  {"body": "Body only",  "userId": 1}),
        ("body",   {"title": "Title only", "userId": 1}),
        ("userId", {"title": "Title",     "body": "Body"}),
    ])
    def test_create_post_with_missing_required_field(
        self, base_url, api_session, missing_field, payload
    ):
        """Error case: Missing required field returns 400 or 422."""
        response = api_session.post(f"{base_url}/posts", json=payload)

        assert response.status_code in [400, 422]

STEP 4: Auth & Authorization Test Design

Auth tests verify both that valid tokens grant access and that missing or invalid tokens are properly rejected.

# tests/test_auth.py
import pytest
import requests

class TestAuthentication:
    """Auth and authorization tests.
    ※ Endpoints like /protected/users are examples for a real production API.
    jsonplaceholder.typicode.com does not implement them.
    Replace with your actual authenticated API before running.
    """

    def test_protected_endpoint_without_token_returns_401(
        self, base_url, api_session
    ):
        """No token: 401 Unauthorized."""
        response = api_session.get(f"{base_url}/protected/users")
        assert response.status_code == 401

    def test_protected_endpoint_with_invalid_token_returns_401(
        self, base_url, api_session
    ):
        """Invalid token: 401 Unauthorized."""
        headers = {"Authorization": "Bearer INVALID_TOKEN"}
        response = api_session.get(f"{base_url}/protected/users", headers=headers)
        assert response.status_code == 401

    def test_protected_endpoint_with_valid_token_returns_200(
        self, base_url, api_session, auth_headers
    ):
        """Valid token: 200 OK."""
        response = api_session.get(
            f"{base_url}/protected/users", headers=auth_headers
        )
        assert response.status_code == 200

    def test_user_cannot_access_other_users_data(
        self, base_url, api_session, auth_headers
    ):
        """Authorization: Access to another user's private data returns 403."""
        response = api_session.get(
            f"{base_url}/users/999/private", headers=auth_headers
        )
        assert response.status_code == 403

    @pytest.mark.parametrize("expired_token", [
        "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.expired",
        "Bearer ",       # empty token
        "InvalidFormat", # missing Bearer prefix
    ])
    def test_invalid_token_formats_return_401(
        self, base_url, api_session, expired_token
    ):
        """Various invalid token formats return 401."""
        headers = {"Authorization": expired_token}
        response = api_session.get(f"{base_url}/protected/users", headers=headers)
        assert response.status_code == 401

STEP 5: Boundary Value & Edge Case Test Design

Boundary value tests verify API stability under extreme inputs — empty values, maximum lengths, wrong types, and security payloads.

BOUNDARY_TITLES = [
    ("empty_string",    "",                                    [400, 422]),
    ("single_char",     "A",                                   [200, 201]),
    ("max_length",      "A" * 255,                             [200, 201]),
    ("over_max_length", "A" * 256,                             [400, 422]),
    ("special_chars",   "!@#$%^&*()",                          [200, 400]),
    ("emoji",           "📝 Test Post 🚀",                     [200, 201]),
    # SQL injection test — goal: verify safe handling, not rejection
    # ✅ No 500 error  ✅ No DB error details exposed  ✅ No auth bypass
    # ⚠️ Never run against production or third-party APIs. Test env only.
    # 💡 Sanitizing APIs may return 200 — that's valid. What matters is no 500.
    # Reference: OWASP Testing Guide - Testing for SQL Injection
    ("sql_injection",   "' OR '1'='1",                         [200, 400, 422]),
    # XSS test — verify the script tag is handled safely (no 500, no execution)
    ("xss_script",      "<script>alert('xss')</script>",       [200, 400, 422]),
]

class TestBoundaryValues:

    @pytest.mark.parametrize("case_name, title, expected_statuses", BOUNDARY_TITLES)
    def test_post_title_boundary(
        self, base_url, api_session, case_name, title, expected_statuses
    ):
        """Boundary value tests for the title field."""
        payload = {"title": title, "body": "Body", "userId": 1}
        response = api_session.post(f"{base_url}/posts", json=payload)

        assert response.status_code in expected_statuses, \
            f"Case: {case_name}, got {response.status_code}"

    def test_pagination_first_page(self, base_url, api_session):
        """Pagination: First page returns at most the requested count."""
        response = api_session.get(f"{base_url}/posts?_page=1&_limit=10")
        data = safe_json(response)

        assert response.status_code == 200
        assert len(data) <= 10

    def test_pagination_beyond_last_page_returns_empty(self, base_url, api_session):
        """Pagination: Page beyond end returns empty list (not 404)."""
        response = api_session.get(f"{base_url}/posts?_page=99999&_limit=10")

        assert response.status_code == 200
        assert safe_json(response) == []

STEP 6: Schema Validation — Type and Format Verification

Schema validation systematically confirms field types and required fields across responses.

# pip install jsonschema
from jsonschema import validate, ValidationError, FormatChecker
import pytest

# 💡 Note: format validators (email, uri, etc.) are only enforced
#    when FormatChecker() is passed — omitting it silently skips format checks.

USER_SCHEMA = {
    "type": "object",
    "required": ["id", "name", "email", "username"],
    "additionalProperties": False,  # Reject undeclared fields (strict mode — use with caution)
    # ⚠️ If the API adds a new field (even a backward-compatible one), this will break.
    # You'll need to update the schema whenever the API evolves.
    # Skip this for beginners. Relevant in Consumer-Driven Contract Testing (Pact, etc.)
    "properties": {
        "id":       {"type": "integer"},
        "name":     {"type": "string", "minLength": 1},
        "email":    {"type": "string", "format": "email"},
        "username": {"type": "string", "minLength": 1},
    }
}

POST_SCHEMA = {
    "type": "object",
    "required": ["id", "title", "body", "userId"],
    "properties": {
        "id":     {"type": "integer"},
        "title":  {"type": "string"},
        "body":   {"type": "string"},
        "userId": {"type": "integer"},
    }
}

class TestResponseSchema:

    def test_user_response_schema(self, base_url, api_session):
        """Schema: User response matches expected schema."""
        response = api_session.get(f"{base_url}/users/1")
        data = safe_json(response)

        try:
            validate(
                instance=data,
                schema=USER_SCHEMA,
                format_checker=FormatChecker()
            )
        except ValidationError as e:
            pytest.fail(f"Schema validation failed: {e.message}")

    def test_post_list_schema(self, base_url, api_session):
        """Schema: First 5 posts in the list match expected schema."""
        response = api_session.get(f"{base_url}/posts")
        posts = safe_json(response)

        for post in posts[:5]:
            try:
                validate(
                    instance=post,
                    schema=POST_SCHEMA,
                    format_checker=FormatChecker()
                )
            except ValidationError as e:
                pytest.fail(f"Post ID {post.get('id')}: schema failed — {e.message}")

STEP 7: PUT/PATCH Test Design

Update tests verify that changes are actually reflected in the response. Always check the updated value, not just the status code.

class TestUpdatePost:

    def test_patch_post_returns_200(self, base_url, api_session):
        """Happy path: Partial update returns 200."""
        payload = {"title": "Updated Title"}
        response = api_session.patch(f"{base_url}/posts/1", json=payload)
        data = safe_json(response)

        assert response.status_code == 200
        assert data["title"] == "Updated Title"

    def test_put_post_returns_200(self, base_url, api_session):
        """Happy path: Full replacement returns 200."""
        payload = {
            "id": 1,
            "title": "Replaced Title",
            "body": "Replaced body",
            "userId": 1
        }
        response = api_session.put(f"{base_url}/posts/1", json=payload)
        data = safe_json(response)

        assert response.status_code == 200
        assert data["title"] == payload["title"]
        assert data["body"] == payload["body"]

    def test_patch_nonexistent_post_returns_404(self, base_url, api_session):
        """Error case: PATCH on non-existent post returns 404."""
        response = api_session.patch(
            f"{base_url}/posts/99999", json={"title": "Update"}
        )
        assert response.status_code == 404

STEP 8: Mock Tests — Removing External API Dependencies

External API calls (payments, email, SMS) can't always be hit from test environments. The responses library lets you mock HTTP calls without any real network traffic.

# pip install responses
import responses
import requests
import pytest

# responses mocks HTTP calls at the requests library level.
# Use it when testing code that calls external services you don't control.

@responses.activate
def test_external_api_mock():
    """Mock an external API call — no real network needed."""
    responses.add(
        responses.GET,
        "https://api.example.com/users/1",
        json={"id": 1, "name": "Test User"},
        status=200
    )

    response = requests.get("https://api.example.com/users/1")

    assert response.status_code == 200
    assert safe_json(response)["name"] == "Test User"
    assert len(responses.calls) == 1  # Verify it was called exactly once

@responses.activate
def test_api_error_response_with_mock():
    """Simulate an error response using a mock."""
    responses.add(
        responses.GET,
        "https://api.example.com/users/999",
        json={"message": "Not Found"},
        status=404
    )

    response = requests.get("https://api.example.com/users/999")

    assert response.status_code == 404

STEP 9: DELETE Test Design

DELETE tests verify both that the deletion succeeds and that the deleted resource is no longer accessible.

@pytest.fixture
def test_post(base_url, api_session):
    """Create a test post, yield its ID, then clean it up."""
    payload = {"title": "Test Post", "body": "Created by fixture", "userId": 1}
    response = api_session.post(f"{base_url}/posts", json=payload)
    post_id = safe_json(response)["id"]

    yield post_id

    # teardown — protect with try/except so cleanup failure doesn't affect test result
    try:
        api_session.delete(f"{base_url}/posts/{post_id}")
    except Exception as e:
        print(f"Cleanup failed for post_id={post_id}: {e}")

class TestDeletePost:

    def test_delete_post_returns_204(self, base_url, api_session):
        """Happy path: Delete returns 204."""
        response = api_session.delete(f"{base_url}/posts/1")
        assert response.status_code == 204

    def test_delete_post_response_body_is_empty(self, base_url, api_session):
        """Happy path: 204 response has no body."""
        response = api_session.delete(f"{base_url}/posts/1")

        # Per RFC, 204 responses should have no body.
        # Some APIs return empty JSON, empty arrays, or whitespace — verify against your spec.
        assert response.status_code == 204
        assert not response.content
        # If your API returns something: assert response.content in [b"", b"null", b"{}"]

    def test_delete_nonexistent_post_returns_404(self, base_url, api_session):
        """Error case: Deleting non-existent post returns 404."""
        response = api_session.delete(f"{base_url}/posts/99999")
        assert response.status_code == 404

    def test_delete_without_auth_returns_401(self, base_url, api_session):
        """No auth: Delete returns 401."""
        response = api_session.delete(f"{base_url}/protected/posts/1")
        assert response.status_code == 401

    def test_deleted_post_cannot_be_fetched(self, base_url, api_session, test_post):
        """After deletion, the resource returns 404."""
        # NOTE: jsonplaceholder.typicode.com does not persist deletions.
        # This sample assumes a real production API.
        delete_response = api_session.delete(f"{base_url}/posts/{test_post}")
        assert delete_response.status_code == 204

        get_response = api_session.get(f"{base_url}/posts/{test_post}")
        assert get_response.status_code == 404

STEP 10: Network Exception & Timeout Tests

Testing how your code handles network failures is just as important as testing happy paths. Use unittest.mock to simulate these without real network calls.

import pytest
import requests
from unittest.mock import patch

class TestNetworkErrorHandling:

    @patch.object(requests.Session, "get")
    def test_timeout_exception(self, mock_get):
        """Timeout raises Timeout exception (mocked for CI stability)."""
        mock_get.side_effect = requests.exceptions.Timeout

        session = requests.Session()
        with pytest.raises(requests.exceptions.Timeout):
            session.get("https://example.com")

    @patch.object(requests.Session, "get")
    def test_connection_error(self, mock_get):
        """Connection failure raises ConnectionError (mocked — no DNS dependency)."""
        mock_get.side_effect = requests.exceptions.ConnectionError

        session = requests.Session()
        with pytest.raises(requests.exceptions.ConnectionError):
            session.get("https://example.com")

HTTP Status Code Reference for API Testing

⚠️ 5 Common API Test Mistakes

FAQ

📋 Summary

Start by writing one GET test — send a request, assert the status code, and check a required field. From there, add error cases, then auth, then boundary values. The checklist in this article will tell you when you've covered enough.