How do I set up a mock server for testing dependent services during API development?

A mock server is useful when your API depends on other services that may be slow, unstable, unavailable, or expensive to call during development and testing.

Basic approach

1. Identify the external dependencies

   • e.g. payment provider, user profile service, shipping API, internal microservice

2. Define the request/response contract

   • What endpoints does your API call?
   • What headers, query params, and bodies does it send?
   • What responses and error cases do you expect?

3. Choose a mocking tool Common options:

   • WireMock — good for HTTP mocking, flexible, widely used
   • MockServer — good for dynamic expectations and verification
   • json-server — simple REST mock from a JSON file
   • Prism — mock from an OpenAPI spec
   • Postman Mock Server — convenient if you already use Postman
   • MSW (Mock Service Worker) — great for frontend/browser testing
   • Express/FastAPI/Flask custom server — simplest if you want full control

4. Create mock endpoints

   • Set up routes that match the real service
   • Return realistic payloads, status codes, and delays
   • Include success and failure cases

5. Point your API to the mock

   • Use environment variables like:
     • USER_SERVICE_URL=http://localhost:8081
   • Keep the base URL configurable so you can switch between mock and real easily

6. Add test scenarios

   • Success response
   • 400/401/403/404/500 cases
   • Timeout / slow response
   • malformed JSON
   • retries and circuit-breaker behavior

7. Automate it

   • Run the mock server in Docker or via your test framework
   • Start it in CI before integration tests

---

Example: simple mock server with Express

// mock-server.js
const express = require('express');
const app = express();
app.use(express.json());

app.get('/users/:id', (req, res) => {
  if (req.params.id === '123') {
    return res.json({ id: '123', name: 'Jane Doe' });
  }
  return res.status(404).json({ error: 'User not found' });
});

app.post('/payments', (req, res) => {
  return res.status(201).json({ paymentId: 'pay_abc123', status: 'approved' });
});

app.listen(8081, () => console.log('Mock server running on http://localhost:8081'));

Run it:

node mock-server.js

Then configure your app:

export USER_SERVICE_URL=http://localhost:8081
export PAYMENT_SERVICE_URL=http://localhost:8081

---

Example: WireMock

If you want a more production-like HTTP mock:

docker run -it --rm -p 8081:8080 wiremock/wiremock

Then create stubs like:

{
  "request": {
    "method": "GET",
    "urlPath": "/users/123"
  },
  "response": {
    "status": 200,
    "jsonBody": {
      "id": "123",
      "name": "Jane Doe"
    },
    "headers": {
      "Content-Type": "application/json"
    }
  }
}

---

Best practices

• Keep mocks versioned with your code
• Make mock responses match the real service closely
• Test both happy path and failure modes
• Avoid over-mocking: keep at least some end-to-end tests against real dependencies or staging
• If possible, generate mocks from an OpenAPI spec to reduce drift
• Use contract tests (e.g. Pact) if services are owned by separate teams

---

Recommended setup for most teams

• Local dev: lightweight custom mock or WireMock
• CI integration tests: WireMock/MockServer in Docker
• Cross-team API contracts: Pact or OpenAPI-based mocking

If you want, I can give you a mock server setup for a specific stack like Node.js, Python/FastAPI, Java/Spring, .NET, or Docker Compose.