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

A good way to set up a mock server for testing dependent services during API development is to treat it like a lightweight stand-in for the real dependency: define the contract, implement predictable responses, and run it locally or in CI so your API can develop against stable behavior.

Typical setup

1. Identify the dependency contract

Figure out:

• endpoints your API calls
• request methods and payloads
• headers/auth requirements
• expected responses for success and failure cases
• timing/error behavior you want to simulate

If you have an OpenAPI/Swagger spec or recorded examples, that’s ideal.

2. Choose a mocking approach

Common options:

• Static mock server: returns fixed responses for routes
  Good for simple testing.
• Contract-based mock server: uses OpenAPI/JSON schema to validate requests and return examples
  Good for API development and contract testing.
• Programmable mock server: lets you write custom logic for responses
  Good for simulating complex state or edge cases.

Popular tools:

• WireMock — very common for HTTP stubs
• Mockoon — easy GUI-based mocking
• Prism — mocks from OpenAPI specs
• json-server — quick REST-style mock API
• MSW — if mocking at frontend/network layer in browser/node tests

3. Define mock endpoints

Example with WireMock-style behavior:

• GET /users/123 → returns a user object
• POST /payments → returns 201 or 402
• GET /inventory/sku-1 → returns stock count or 404

You should mock:

• happy path
• validation errors
• auth failures
• downstream timeouts
• 5xx errors

4. Make it configurable

Use environment variables so your API can switch between:

• real service in production
• mock service in local dev/test

Example:

DEPENDENCY_BASE_URL=http://localhost:8081

5. Run the mock server alongside your API

Options:

• locally as a separate process
• in Docker Compose
• in CI pipeline
• as a test fixture during integration tests

Example docker-compose.yml:

services:
  api:
    build: .
    environment:
      DEPENDENCY_BASE_URL: http://mock:8080
    depends_on:
      - mock

  mock:
    image: wiremock/wiremock
    ports:
      - "8080:8080"
    volumes:
      - ./mocks:/home/wiremock

6. Add test cases against the mock

Write integration tests to verify:

• your API sends the right requests
• your API handles responses correctly
• fallback/retry logic works
• error handling is correct

7. Keep mocks in sync with the real service

To avoid drift:

• store mock definitions in version control
• generate mocks from the OpenAPI spec if possible
• update mocks when the dependency contract changes
• add contract tests to detect mismatches

---

Simple example: WireMock

If you want a quick mock server:

Run WireMock

docker run -p 8080:8080 wiremock/wiremock

Add a stub

Create mappings/user.json:

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

Now your API can call:

http://localhost:8080/users/123

---

Best practices

• Mock only external dependencies, not your own logic.
• Include realistic failure cases, not just happy paths.
• Prefer contract-driven mocks over hand-written one-offs when possible.
• Keep mock data deterministic for stable tests.
• Version mocks alongside API code.
• Use the mock server in local dev and CI, but validate against the real service too.

If you tell me your stack (Node, Python, Java, .NET, etc.) and the type of dependency you want to mock, I can show you a concrete setup and example config.