Mocking API Responses

Overview

The testing-api repository serves as a centralized source of truth for API response structures within the Supervised AI platform. By utilizing the provided response.json files and schema samples, frontend and consumer-side developers can build robust mock servers. This allows for parallel development, ensuring that client-side applications are ready even before the backend services are fully deployed.

Using Response Samples

Each endpoint directory contains a response.json file. These files represent the standard success payload (HTTP 200/201) and include realistic data types and structures required by the Supervised AI ecosystem.

Structure of response.json

The JSON samples are designed to be consumed directly by mock utilities. A typical sample follows this format:

{
  "status": "success",
  "data": {
    "id": "uuid-v4-string",
    "attributes": {
       "name": "Sample Task",
       "type": "classification"
    }
  },
  "meta": {
    "timestamp": "2023-10-27T10:00:00Z"
  }
}

Setting Up a Mock Server

You can leverage these samples to create a local mock environment using various industry-standard tools.

Option 1: Prism (OpenAPI Mocking)

If the repository includes OpenAPI/Swagger definitions, use Prism to turn your response.json files into a live HTTP server:

# Install Prism
npm install -g @stoplight/prism-cli

# Run a mock server using the local spec
prism mock ./path/to/openapi.yaml

Option 2: JSON Server

For a quick, RESTful mock server based directly on the response.json files:

1. Create a db.json that imports your samples.
2. Run json-server:

npx json-server --watch db.json --port 4000

Integrating with Frontend Development

When developing frontend components, you can point your environment variables to the mock server instead of the production API.

Example: Fetching Mock Data in React/Vue

const API_BASE_URL = process.env.REACT_APP_API_URL || 'http://localhost:4000';

async function fetchProjectData(projectId: string) {
  const response = await fetch(`${API_BASE_URL}/projects/${projectId}`);
  // This will return the structure defined in response.json
  return response.json();
}

Mocking Error States

While response.json typically covers success scenarios, the repository may also include error_400.json or error_500.json files. These should be used to test:

• Form validation UI.
• Global error boundary handling.
• Retry logic in consumer services.

Best Practices

• Keep Samples Updated: Always pull the latest changes from testing-api to ensure your mocks match the current backend contract.
• Validation: Use the schemas provided in the repository to validate your mock server's output during CI/CD pipelines.
• Automated Testing: Use these JSON samples as the "Expected" value in your frontend unit tests (e.g., Jest/Vitest) to ensure your parsers and transformers work correctly.