DEV Community: Maesi

Ensuring Compliance with the HTTP API Contract Using Mokapi for Request Forwarding and Validation

Maesi — Tue, 09 Dec 2025 10:00:00 +0000

In modern distributed systems, APIs are everywhere — frontend-to-backend, backend-to-backend, microservices communicating internally, mobile apps, test automation tools, and more. Each interaction relies on a shared API contract, often expressed through an OpenAPI specification. Even small deviations can introduce bugs, break integrations, or slow down development.

By placing Mokapi between a client and a backend, you can ensure that every request and response adheres to your OpenAPI specification. With a few lines of JavaScript, Mokapi can forward requests to your backend while validating both sides of the interaction. This provides a powerful way to enforce API correctness — whether the client is a browser, Playwright tests, your mobile app, or even another backend service.

In this article, I explore how Mokapi can act as a contract-enforcing validation layer and why this approach benefits frontend developers, backend teams, QA engineers, and platform engineers alike.

How to Use Mokapi for API Validation with Request Forwarding?

Mokapi cannot only be used for mocking APIs, but it can also sit between any
consumer and a backend service to validate real traffic. Using a small
JavaScript script, Mokapi can forward requests to your backend and
validates both requests and responses.

import { on } from 'mokapi';
import { fetch } from 'mokapi/http';

/**
 * This script demonstrates how to forward incoming HTTP requests
 * to a real backend while letting Mokapi validate responses according
 * to your OpenAPI spec.
 *
 * The script listens to all HTTP requests and forwards them based
 * on the `request.api` field. Responses from the backend are
 * validated when possible, and any errors are reported back to
 * the client.
 */
export default async function () {

    /**
     * Register a global HTTP event handler.
     * This function is called for every incoming request.
     */
    on('http', async (request, response) => {

        // Determine the backend URL to forward this request to
        const url = getForwardUrl(request)

        // If no URL could be determined, return an error immediately
        if (!url) {
            response.statusCode = 500;
            response.body = 'Failed to forward request: unknown backend';
            return;
        } 

        try {
            // Forward the request to the backend
            const res = await fetch(url, {
                method: request.method,
                body: request.body,
                headers: request.header,
                timeout: '30s'
            });

            // Copy status code and headers from the backend response
            response.statusCode = res.statusCode;
            response.headers = res.headers

            // Check the content type to decide whether to validate the response
            const contentType = res.headers['Content-Type']?.[0] || '';

            if (contentType.includes('application/json')) {
                // Mokapi can validate JSON responses automatically
                response.data = res.json();
            } else {
                // For other content types, skip validation
                response.body = res.body;
            }

        } catch (e) {
            // Handle any errors that occur while forwarding
            response.statusCode = 500;
            response.body = e.toString();
        }
    });

    /**
     * Maps the incoming request to a backend URL based on the API name
     * defined in the OpenAPI specification (`info.title`).
     * @see https://mokapi.io/docs/javascript-api/mokapi/eventhandler/httprequest
     *
     * @param request - the incoming Mokapi HTTP request
     * @returns the full URL to forward the request to, or undefined
     */
    function getForwardUrl(request: HttpRequest): string | undefined {
        switch (request.api) {
            case 'backend-1': {
                return `https://backend1.example.com${request.url.path}?${request.url.query}`;
            }
            case 'backend-2': {
                return `https://backend1.example.com${request.url.path}?${request.url.query}`;
            }
            default:
                return undefined;
        }
    }
}

For each interaction, Mokapi performs four important steps:

1. Validates incoming requests

Mokapi checks every incoming request against your OpenAPI specification:

HTTP method
URL & parameters
headers
request body

If the client sends anything invalid, Mokapi blocks it and returns a clear
validation error.

2. Forwards valid requests to your backend

If the request is valid, Mokapi forwards it unchanged to the backend using JavaScript.

No changes are required in your backend.
No additional infrastructure is necessary.

3. Validates backend responses

Once the backend responds, Mokapi validates the response against the OpenAPI specification:

status codes
headers
response body

If something doesn't match the contract, Mokapi blocks it and sends a validation error back to the client.

4. Return the validated response to the client

Only responses that pass validation reach the client, guaranteeing contract fidelity end-to-end.

Where You Can Use Mokapi for Request Forwarding and Validation

Mokapi’s forwarding and validation capabilities make it useful far beyond local development or Playwright scripting.

Between Frontend and Backend

Placing Mokapi between your frontend and backend ensures:

automatic request and response validation
immediate detection of breaking changes
backend and API specification evolve together
fewer “why is the frontend broken?” debugging loops

Frontend developers can experiment with confidence, knowing the backend
cannot silently diverge from the published contract.

Between Backend Services (Service-to-Service)

In microservice architectures, API drift between services is a frequent cause of instability.
Routing service-to-service traffic through Mokapi gives you:

strict contract enforcement between services
early detection of incompatible changes
stable integrations even as teams evolve independently
clear validation errors during development and CI

Mokapi becomes a lightweight, spec-driven contract guardian across your backend ecosystem.

In Automated Testing (e.g., Playwright)

This is one of the most powerful setups.

Playwright → Mokapi → Backend

Benefits:

CI fails immediately when the backend breaks the API contract
tests interact with the real backend, not mocks
validation errors are clear and actionable
tests remain simpler — no need to validate everything in Playwright

Your tests are guaranteed to hit a backend that actually matches the API contract.

In Kubernetes Test Environments

Mokapi can also be used in temporary or preview environments to ensure contract validation across the entire cluster.

In Kubernetes, Mokapi can be deployed as:

a sidecar container
a standalone validation layer in front of backend services
a temporary component inside preview environments

This brings:

consistent contract validation for all cluster traffic
early detection of breaking API changes before staging
contract enforcement without modifying backend services
transparent operation — apps talk to Mokapi, Mokapi talks to the backend

You can integrate Mokapi into Helm charts, GitOps workflows, or test namespaces.

Why Teams Benefit from Using Mokapi Between Client and Backend

Automatic Contract Enforcement

Every interaction is validated against your OpenAPI specification. Your backend can no longer quietly drift from the contract.

Immediate Detection of Breaking Changes

Issues are caught early, not just in staging or production, such as:

renamed or missing fields
wrong or inconsistent formats
unexpected status codes
mismatched data types

More Reliable Frontend Development

Frontend teams get:

consistent, validated API responses
fewer sudden breaking changes
a smoother development workflow

This reduces context-switching and debugging time.

Better Collaboration Between Teams

With Mokapi validating both sides:

backend developers instantly see when they violate the contract
frontend engineers get stable, predictable APIs
QA gets reliable test environments
platform engineers reduce risk during deployments

Mokapi becomes a shared API contract watchdog across the organization.

Smooth Transition from Mocks to Real Systems

Teams often start with mocked endpoints in early development. Later, they can simply begin forwarding requests to the
real backend—while keeping validation in place.

Conclusion

Using Mokapi between frontend and backend, between backend services, or inside Kubernetes environments provides:

strong contract enforcement
automatic validation for every interaction
early detection of breaking changes
stable multi-team integration
more reliable CI pipelines
a smooth path from mocking to real backend validation

Mokapi ensures your API stays aligned with its specification, no matter how quickly your system evolves.

Mokapi becomes your always-on API contract guardian — lightweight, transparent, and spec-driven.

This article is also available on my website: Mokapi.io

Testing Kafka Workflows Without Kafka — With Playwright & Mokapi

Maesi — Wed, 20 Aug 2025 20:30:38 +0000

Event-driven systems are powerful — but testing them can feel heavy.

Spinning up a Kafka cluster, checking if specifications are met, producing test input, and reading results from topics… it adds a lot of overhead, especially in CI pipelines.

What if you could test Kafka workflows without running a Kafka cluster?

That’s exactly what Mokapi enables.

Why This Matters

Testing event-driven workflows usually means juggling infrastructure:

Running a local or containerized Kafka broker
Making sure topics and schemas match the spec
Setting up test producers and consumers
Verifying results at the topic level

For end-to-end workflow tests, this slows you down. With Mokapi, you can skip the cluster and use a Kafka-like REST API for producing and consuming records — perfectly aligned with your AsyncAPI specs.

The Testing Scenario

Let’s walk through a realistic workflow.

In our system:

A foreign system sends a command to document.send-command (Kafka topic).
Our backend consumes this command, simulates sending the document, and then publishes a result to document.send-event.

Here’s how we test this with Playwright + Mokapi:

Produce input — Playwright sends a Kafka record into document.send-command using Mokapi’s REST API.
Backend processes the command — our Node.js backend consumes the command and publishes the outcome into document.send-event.
Verify the result — Playwright retrieves the new record from document.send-event via Mokapi’s REST API and checks the documentId and status.

This gives us full end-to-end confidence without running Kafka.

Example Setup

👉 The full example project is available here: mokapi-kafka-workflow.

Backend: Node.js consumer + producer
Mokapi: mocks the Kafka cluster using AsyncAPI
Playwright: drives the test by producing and verifying messages

Playwright doesn’t open a browser UI in this case — it’s simply used as a testing framework with clean assertions and easy integration into CI.

Conclusion

This example shows how to build an end-to-end Kafka workflow test with Playwright and Mokapi:

✅ Simple setup — no Kafka broker required
✅ Produce and consume messages via REST
✅ Works seamlessly in CI/CD pipelines

And this pattern scales: you can expand it to multiple backends and topics while keeping tests easy to write and maintain.

With Mokapi, testing Kafka workflows becomes lightweight, reliable, and spec-driven.

🔗 Read the full tutorial on mokapi.io

Acceptance Testing with Mokapi: Focus on What Matters

Maesi — Tue, 08 Jul 2025 11:24:48 +0000

In today’s fast-paced development cycles, it’s crucial to ensure your software meets real user expectations. While unit tests validate internal code, acceptance testing answers the bigger question: Does the system behave as users expect? This post explores the value of acceptance tests and how Mokapi supports it by simulating APIs, validating specifications, and enabling robust, realistic test cases.

Why Acceptance Testing

Software testing is not merely a box to check—it is a fundamental process to answer one critical question: Is our software releasable?

Among the various levels of testing, acceptance testing offers the most direct insight into whether the software meets business and user expectations. It bridges the gap between the world of users and the inner workings of the code by turning expectations into precise, executable checks on system behavior.

The Nature of Acceptance Tests

At its core, an acceptance test is an executable specification of how a system should behave, written from a user’s perspective. It is not concerned with how the system is implemented, but with what it does—its behavior and its outcomes.

While unit tests focus on individual components, acceptance tests focus on the system's intent. They clarify what should happen when a user interacts with the software under certain conditions.

When we get the level of abstraction right, acceptance tests become clear, precise, and maintainable. They reflect scenarios that matter to users, expressed in a way that is both easy to read and easy to execute. They serve as living documentation that evolves with the system and its requirements.

Solving Ambiguity and Ensuring Reproducibility

One of the most challenging aspects of software development is not writing code—it is understanding the problem clearly and expressing it precisely. Programs are, after all, specifications of what we want the system to do. But unlike natural languages, which are rich in context and ambiguity, software requires unambiguous clarity.

This is where acceptance testing shines.

By expressing requirements in an executable form, acceptance tests remove ambiguity. They define exactly what needs to happen. Rather than relying on vague documentation or human interpretation, developers, testers, and stakeholders can rely on concrete, shared understanding. The tests describe behavior, not implementation details, which makes them robust to changes in how the system is built, as long as it continues to behave as expected.

Moreover, acceptance tests are reproducible. They can be run automatically, as often as needed, to ensure the software continues to meet its defined expectations. This reproducibility is crucial for modern CI pipelines, where tests are run continuously to catch regressions early

A Contract of Trust

In a collaborative development environment, acceptance tests serve as a contract between the business and the development team. When everyone agrees on the specifications encoded in the tests, there is no room for misinterpretation. The business gets what it asked for, and developers have a reliable guide to follow.

This contract is especially important in agile and iterative processes, where requirements evolve and features are delivered incrementally. With acceptance tests in place, the team always has a clear picture of what "done" means.

Making Software Releasable

Acceptance testing answers a key question: Is the software ready to release? It gives us confidence that the features meet user needs and work correctly. It also checks that we built what was actually requested. Most importantly, it does this in a way that’s automated, repeatable, and reliable.

By aligning development with user intent, removing ambiguity, and validating results, acceptance testing becomes an essential practice—not just for verifying software, but for clearly understanding and specifying it in the first place.

The problem with acceptance testing and 3rd party APIs

Unstable – External APIs can fail randomly, whether due to bugs or release workflows.
No test environment – Many APIs don’t offer a dedicated environment for testing.
Uncontrollable state – It’s often impossible to set up the external system in the desired state for your tests.

These limitations can make acceptance testing brittle and unreliable—unless you can simulate the external system reliably.

How Mokapi Supports Acceptance Testing

That’s where Mokapi comes in. It lets you simulate realistic API behavior in a way that’s fast, accurate, and under your full control.

Acceptance testing becomes significantly more effective with the right tools—especially in complex environments with multiple APIs, microservices, and evolving interfaces. Mokapi was developed to address precisely these challenges. It provides a powerful, flexible, and specification-oriented approach to API simulation, enabling high-quality acceptance testing in a wide variety of scenarios.

Acceptance Testing Across Boundaries

Mokapi makes acceptance testing easier across flexible system boundaries—whether you're focusing on a single microservice or validating your entire architecture—by mocking the APIs they depend on.

Powerful Flexibility for Real-World Scenarios
With Mokapi, you're not limited to ideal cases. The JavaScript-based mock handlers enable the simulation of a wide variety of real-world scenarios, including negative tests, edge cases, and error conditions—all essential for developing robust software. You can programmatically control responses based on request data, headers, or business logic, giving you precise control over your mock's behavior during a test.

This flexibility helps you answer not only the question "Does it work?" but also "Does it work when third-party systems don't."

Specification-Driven Confidence

One of Mokapi's key strengths is its close alignment with API specifications. Mocks are continuously validated against OpenAPI or AsyncAPI definitions, ensuring they accurately reflect the APIs being simulated. This becomes especially valuable as APIs evolve.

When a provider releases a new API version, it can be easily updated in Mokapi. If mock data or API calls no longer conform to the updated specification, Mokapi returns errors that can be caught through acceptance testing. This supports automated API version updates and acts as an early warning system for potential production issues.

Smart Mock Customization with Patch Mechanism

Mokapi supports a patching mechanism for both API specifications and mock data. Patching the specification helps you adopt new API versions more easily while keeping track of your own modifications to the original spec. Patching mock data, on the other hand, allows you to avoid over-mocking—keeping your tests stable and focused, so changes are only required when they’re truly relevant.

Here's an example:

import { on, patch } from 'mokapi';
import { fake } from 'mokapi/faker';

export default function() {
    // Open the OpenAPI pet store specification, resolving all $ref references
    const api = open('pet-store-api.yaml', { as: 'resolved' });

    // Generate a random pet object based on the OpenAPI schema
    const pet = fake(api.components.schemas.pet);

    on('http', (request, response) => {
        // Use the generated pet but override the name to 'Odie'
        response.data = patch(pet, { name: 'Odie' });

        // Alternatively, patch Mokapi's autogenerated response and just set the name
        // response.data = patch(response.data, { name: 'Odie' });
    });
}

This example demonstrates how you can generate valid mock data that conforms to the API specification and then customize only the parts relevant to your test—such as setting a specific pet name—without redefining the entire response structure.

Making Acceptance Testing Sustainable

By combining flexible mocks, specification validation, and a smart patching mechanism, Mokapi makes acceptance testing more resilient, more focused, and easier to maintain. It helps your team test confidently—whether you're building a new feature in isolation, validating complex integrations, or preparing for a production release.

Mokapi doesn’t just enable acceptance testing—it makes it practical, maintainable, and deeply aligned with your evolving system and its requirements.

Ready to get started?

Learn how to set up acceptance tests with Mokapi in your CI/CD pipeline:

👉 Running Mokapi in a CI/CD Pipeline
👉 Mokapi Documentation