{
    "slug": "api_mocking",
    "term": "API Mocking",
    "category": "api_design",
    "difficulty": "intermediate",
    "short": "Prism (OpenAPI mock server), WireMock (HTTP stub server), Mockoon (GUI), and Guzzle MockHandler for PHP unit tests — enabling testing without real API calls.",
    "long": "API mocking tools: Prism — generates a mock server from an OpenAPI spec instantly, returning example responses. WireMock — record real API calls and replay them, or configure stub responses with delays and error simulation. Mockoon — desktop GUI for managing mock APIs. PHP unit tests: Guzzle MockHandler intercepts HTTP at the client level — no actual network connection made. Use cases: test error scenarios (429, 503, timeouts) that are hard to trigger with real APIs, CI without external service dependencies, and frontend development before the backend is ready.",
    "aliases": [
        "API mock",
        "Prism",
        "WireMock",
        "Mockoon",
        "Guzzle MockHandler"
    ],
    "tags": [
        "api-design",
        "testing",
        "tooling"
    ],
    "misconception": "Mocking APIs in tests means making HTTP calls to a local mock server — for unit tests, Guzzle MockHandler intercepts at the HTTP client level without any network connection; mock servers are for integration tests and frontend development.",
    "why_it_matters": "CI tests that make real API calls are slow, flaky (depend on external service availability), and create test data in production systems — HTTP client mocks make tests fast, deterministic, and isolated.",
    "common_mistakes": [
        "Real API calls in unit tests — slow, flaky, require network, create production test data",
        "Mock responses that don't match the actual API spec — tests pass but integration fails",
        "Not testing error scenarios — real APIs fail; mocks must simulate 429, 503, network timeouts",
        "Outdated mock responses — mocks must be updated when the real API contract changes"
    ],
    "when_to_use": [
        "Unit testing code that calls external HTTP APIs — mocks remove network dependency and make tests deterministic.",
        "Developing a consumer before the provider API is ready — a mock server lets both teams work in parallel.",
        "Testing error and edge-case responses (timeouts, 429, 503) that are hard to trigger against a real service."
    ],
    "avoid_when": [
        "Avoid mocking as a substitute for contract or integration tests — mocks can drift from the real API silently.",
        "Do not mock at the HTTP level in integration tests that are specifically meant to verify end-to-end behaviour.",
        "Avoid over-specifying mock responses — brittle mocks that encode every response field break when the API evolves."
    ],
    "related": [
        "api_documentation",
        "api_contract_testing",
        "mocking_best_practices",
        "integration_testing"
    ],
    "prerequisites": [
        "integration_testing",
        "api_contract_testing",
        "unit_testing"
    ],
    "refs": [
        "https://docs.stoplight.io/docs/prism/"
    ],
    "bad_code": "// Real HTTP calls in unit test — slow and fragile:\npublic function testSendConfirmationEmail(): void {\n    $mailer = new SendGridMailer(API_KEY); // Real SendGrid client\n    $result = $mailer->send($email);       // Real HTTP call to SendGrid!\n    $this->assertTrue($result->success);\n    // Fails if: no internet, SendGrid down, API key invalid, rate limited\n}",
    "good_code": "// Guzzle MockHandler — no HTTP in unit tests:\npublic function testSendConfirmationEmail(): void {\n    $mock    = new MockHandler([new Response(202, [], json_encode(['id'=>'test-123']))]);\n    $client  = new Client(['handler' => HandlerStack::create($mock)]);\n    $mailer  = new SendGridMailer($client); // Injected mock client\n    $result  = $mailer->send($email);\n    $this->assertTrue($result->success);\n    $this->assertSame('test-123', $result->messageId);\n    // Fast, deterministic, no network, no side effects\n}",
    "example_note": "The Guzzle MockHandler queues a pre-built response so the mailer test verifies logic and headers without any real network call or SMTP server.",
    "quick_fix": "Use WireMock or Mockery HTTP stubs for integration tests against external APIs — never hit real external APIs in test suites; record real responses once and replay them",
    "severity": "medium",
    "effort": "medium",
    "created": "2026-03-16",
    "updated": "2026-03-31",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/api_mocking",
        "html_url": "https://codeclaritylab.com/glossary/api_mocking",
        "json_url": "https://codeclaritylab.com/glossary/api_mocking.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[API Mocking](https://codeclaritylab.com/glossary/api_mocking) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/api_mocking"
            }
        }
    }
}