Prism API Mocking Tutorial: Speed Up Your Frontend Development

One of the biggest bottlenecks I’ve encountered in full-stack projects is the ‘backend dependency.’ You have the UI designed, the state management ready, and you’re itching to build the features—but the actual API endpoints don’t exist yet. In the past, I’d manually hardcode JSON responses in my frontend code, but that’s a maintenance nightmare.

That’s why I switched to spec-driven development. This prism api mocking tutorial will show you how to use Stoplight Prism to turn your OpenAPI (Swagger) files into a fully functional mock server. Instead of guessing how the data will look, you define the contract first, and Prism handles the rest.

If you’re still deciding on your design tool, you might want to check out my breakdown of Swagger vs Stoplight for API design to see which fits your workflow better.

Prerequisites

Before we dive into the setup, make sure you have the following installed on your machine:

• Node.js (v14 or higher)
• npm or yarn
• An OpenAPI specification file (YAML or JSON format). If you don’t have one, don’t worry—I’ll provide a sample in the next section.

Step 1: Installing Prism

I prefer installing Prism globally so I can spin up mocks for any project regardless of the directory I’m in. Open your terminal and run:

npm install -g @stoplight/prism-cli

To verify the installation, run prism --version. You should see the current version number printed in your console.

Step 2: Preparing Your OpenAPI Specification

Prism relies entirely on your API contract. If your spec is vague, your mock will be useless. For this tutorial, let’s assume we have a simple api.yaml file for a User Profile service:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  name: { type: string }
                  email: { type: string }
              example:
                id: "123"
                name: "Jane Doe"
                email: "jane@example.com"

Step 3: Launching the Mock Server

Now for the magic. To start the mock server, run the following command in the directory where your api.yaml is located:

prism mock api.yaml

By default, Prism will start a server at http://127.0.0.1:4010. As shown in the image below, the terminal will start logging every incoming request and the corresponding response Prism generates based on your spec.

Step 4: Testing Your Mock Endpoints

You can now use curl, Postman, or your browser to hit the endpoint. Try this in your terminal:

curl http://127.0.0.1:4010/users/123

Prism will return the example JSON we defined in the YAML file. One of the best things about Prism is validation. If you try to call an endpoint that isn’t in your spec, or if you send a request with missing required parameters, Prism will return a detailed error message telling you exactly what’s wrong with your request.

Pro Tips for Advanced Mocking

1. Dynamic Responses

If you need different responses for different scenarios (e.g., a 404 for a missing user), you can use the Prefer header. By adding Prefer: code=404 to your request headers, Prism will simulate that specific response code, provided it’s defined in your OpenAPI spec.

2. Integration with Frontend Tooling

In my experience, the best way to use Prism is to add it to your package.json scripts. This ensures everyone on your team uses the same mock version:

"scripts": {
  "mock": "prism mock api.yaml"
}

If you find Prism too lightweight and need a full GUI to manage complex stateful mocks, I highly recommend my Mockoon tutorial for beginners.

Troubleshooting Common Issues

• Port Conflict: If port 4010 is taken, use prism mock api.yaml -p 5000 to specify a custom port.
• CORS Errors: If your frontend app is blocked by CORS, Prism usually handles this by default, but double-check your browser console.
• Spec Errors: If Prism fails to start, your YAML might have indentation errors. Use an online OpenAPI validator to clean it up.

What’s Next?

Now that you have a working mock, you can build your entire frontend integration layer without waiting for a single line of backend code to be written. Once the real API is ready, you simply change the BASE_URL in your environment variables from localhost:4010 to your staging server.

Want to automate your workflow further? Start exploring how to integrate these mocks into your CI/CD pipeline to run contract tests automatically.