Skip to main content

Mock API Servers

Staqr uses Stoplight Prism to provide mock API servers based on OpenAPI specifications. This enables frontend development and contract testing without requiring live Commerce or Platform backend services.

Quick Start​

# Start all mock servers
npm run mocks:start

# Check status
docker ps --filter "name=mock"

# View logs
npm run mocks:logs

# Stop mock servers
npm run mocks:stop

Available Mock Servers​

ServicePortBase PathDescription
Staqr Platform API4610/Core platform API (full spec)
Commerce v0 (Legacy)4620/api/restLegacy Commerce API (lite spec)
Commerce v14621/api/rest/v1Commerce v1 API (lite spec)
Commerce v2 (Generic)4622/Commerce Generic API (full spec)
note

Mock ports (461x, 462x) are deliberately different from production ports (4600, 8080) to avoid conflicts when running both simultaneously.

Testing Mock Endpoints​

# Staqr Platform API
curl http://localhost:4610/compliance/jurisdiction/nz/config | jq .

# Commerce v1 API
curl http://localhost:4621/api/rest/v1/accountManagement/sellers | jq .

# Commerce v2 API (POST example)
curl -X POST http://localhost:4622/account/contactCategory \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

Frontend Development with Mocks​

Temporarily modify packages/react-ui/vite.config.ts proxy target to use mock ports, or stop the real backend and start mocks on the expected ports.

Option 2: Direct API Calls​

For isolated component testing:

const MOCK_API_URL = 'http://localhost:4610';

const response = await fetch(`${MOCK_API_URL}/compliance/jurisdiction/nz/config`);
const data = await response.json();

Option 3: Environment Variable​

Copy .env.development.local.example to .env.development.local in packages/react-ui/:

# Use mock API instead of real backend
VITE_API_BASE_URL=http://localhost:4610

Contract Testing​

Contract tests validate that Staqr's API calls match the OpenAPI specifications.

Running Contract Tests​

# Prerequisites: Start mocks first
npm run mocks:start

# Run contract tests
npm run test:contracts

Writing Contract Tests​

import { describe, expect, it } from 'vitest'
import axios from 'axios'

const COMMERCE_V1_URL = 'http://localhost:4621/api/rest/v1'

describe('My Contract Test', () => {
    it('should call endpoint with correct structure', async () => {
        const response = await axios.get(
            `${COMMERCE_V1_URL}/accountManagement/customers`
        )

        // Prism validates the request and generates schema-compliant response
        expect(response.status).toBe(200)
        expect(response.data).toBeDefined()
    })
})

Mock Data Characteristics​

Prism mock servers generate data dynamically:

  • Realistic but fake: Names, emails, addresses are generated using Faker.js
  • Schema-compliant: Responses always match the OpenAPI specification
  • Stateless: Each request is independent (no data persistence)
  • Deterministic with seed: Same seed produces consistent data

Limitations​

LimitationDescriptionWorkaround
No AuthenticationMocks don't validate tokensTest auth separately
No StatePOST/PUT doesn't persistUse real backend for state tests
Schema ComplexitySome Commerce v0 endpoints failUse v1/v2 APIs instead
Lite SpecsCommerce v0/v1 have reduced endpointsFull specs cause Prism to hang

"Schema too complex" Error​

Some Commerce v0 endpoints have deeply nested schemas that Prism cannot generate mock data for. These return:

{"type":"SCHEMA_TOO_COMPLEX","title":"Schema too complex"}

Workaround: Use Commerce v1 or v2 APIs which have cleaner schemas.

NPM Scripts Reference​

CommandDescription
npm run mocks:startStart all 4 Prism mock servers
npm run mocks:stopStop all mock servers
npm run mocks:logsView combined mock server logs
npm run test:contractsRun contract test suite

Docker Compose Services​

Mocks are defined in docker-compose.yml:

services:
  prism-staqr:
    image: stoplight/prism:latest
    ports: ["127.0.0.1:4610:4010"]

  prism-commerce-v0:
    image: stoplight/prism:latest
    ports: ["127.0.0.1:4620:4010"]

  prism-commerce-v1:
    image: stoplight/prism:latest
    ports: ["127.0.0.1:4621:4010"]

  prism-commerce-v2:
    image: stoplight/prism:latest
    ports: ["127.0.0.1:4622:4010"]
Security

Mocks bind to 127.0.0.1 only (localhost) - they are not accessible from other machines.

Troubleshooting​

Mock server not responding​

# Check container status
docker ps --filter "name=mock"

# Check logs for errors
docker logs staqr-mock-api
docker logs commerce-v1-mock-api

# Restart mocks
npm run mocks:stop && npm run mocks:start

Connection refused​

Ensure Docker is running:

docker info

Tests skip with "mock not available"​

# Verify mocks are running
curl -s http://localhost:4610 | head -1
curl -s http://localhost:4621/api/rest/v1/accountManagement/sellers | head -1

See Also​