Mock APIs

A collection of mock API endpoints designed to facilitate end-to-end testing development. This project provides a set of simulated APIs that mimic real-world services, allowing developers to test their applications without relying on actual external services.

The service provides mock endpoints and test endpoints.

• Mock endpoints are endpoints that simulate the behavior of the real service. They should be called from your application code.
• Test endpoints are endpoints that aren’t present in the real service, but are provided here to help you test your application. They should be called from your test code. These endpoint facilitates tasks such as setting up scenarios and verifying the state of the system.

Contributions for more APIs are welcome!

API list

<!-- begin api list --> <!-- prettier-ignore -->

|                     API                     | Description | | --- | --- | | OAuth 2.0 / OIDC | A mock OAuth 2.0 and OpenID Connect provider API that lets users authenticate as anyone they wish. | | Eventpop | A mock API that implements a subset of the Eventpop Public API. | | GitHub | A mock API that implements a subset of the GitHub API. | | OpenAI | A mock API that implements a subset of the OpenAI API. | | LINE | A mock API that implements a subset of the LINE Messaging API and LINE Login API. | | Vonage | A mock API that implements a subset of the Vonage SMS API for sending SMS messages. | | dtinth/kio | A mock API that implements the endpoints expected by dtinth/kio, a geeky self-checkin kiosk. | | OpnPayments | A mock API that implements a subset of the OpnPayments API for receiving payments. | | SMSKUB | A mock API that implements a subset of the SMSKUB API for sending SMS quick messages. |

<!-- end api list -->

Example use case

Imagine you are developing an application that sends SMS messages through an SMS API provider, and you want to write end-to-end tests your app that verifies the SMS functionality. You can:

1. Configure your application code to send SMS messages through the mock SMS API instead of the real API when certain conditions are met (e.g. when the phone number matches a certain pattern). (Make sure to turn this off in production!)
2. Write your end-to-end tests, filling in the phone number with a test phone number. This should cause your application to send the SMS through the mock SMS API. Instead of sending a real SMS, the mock SMS API will temporarily store the SMS message in the database.
3. Call the test endpoint to retrieve the SMS messages sent to the test phone number, and verify that the SMS message was sent correctly.

Demo

You can explore the available APIs and their documentation at our demo instance:

https://mockapis.onrender.com/

Running with Docker

Using Pre-built Image

For quick setup without building from source, you can use the pre-built Docker image. Create a docker-compose.yml file with the following content:

services:
  redis:
    image: "redis:latest"
  mockapis:
    image: ghcr.io/dtinth/mockapis:main
    environment:
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
    ports:
      - "46982:46982"

Then run:

docker compose up -d

This will start the Mock APIs service using the latest pre-built image from the GitHub Container Registry.

Building from Source

If you plan to make changes to the Mock APIs or want to build from source, you can use the docker-compose.yml file provided in the repository. Clone the repository and run:

docker compose up -d

This will build the Docker image from the source code in the repository and start the service.

Features

• Multiple mock API endpoints simulating various services without the need for authentication or API keys (any key is accepted)
• CORS support for cross-origin requests
• Testing endpoints for verifying that your app calls the correct APIs

Getting Started

To run the project locally:

1. Clone the repository
2. Install dependencies with bun install
3. Start the development server with bun dev

The server will start, and you can access the Swagger UI at http://localhost:46982.

Contributing

We welcome contributions to expand and improve the Mock APIs project! Here are some ways you can contribute:

1. Add new mock API endpoints
2. Improve existing API simulations
3. Enhance documentation
4. Fix bugs or improve performance
5. Improve test coverage

Development Guidelines

To maintain code quality and avoid common mistakes, please follow these guidelines when contributing:

0. Follow Existing Patterns

Before implementing new features, always study existing implementations first:

• For OAuth flows, see src/apis/eventpop.ts as the reference pattern
• For API structure, examine similar APIs in the src/apis/ directory
• For testing approaches, review existing test files

Common mistake: Overengineering solutions instead of following established patterns. For example, OAuth authorize endpoints should typically just redirect to the existing OAuth infrastructure rather than creating custom HTML pages.

// ✅ Good - Follow the eventpop.ts pattern
.get("/oauth/authorize", ({ request }) => {
  return redirect(
    `/oauth/protocol/openid-connect/auth?${new URL(request.url).searchParams}`
  );
})

// ❌ Bad - Overengineering with custom HTML generation
.get("/oauth/authorize", () => {
  return generateComplexAuthorizePage(/* ... */);
})

1. Use Proper Testing Utilities

Always use the configured testing utilities from src/apis/test-utils/:

• Use api for typed API calls
• Use apiFetch for raw HTTP requests (e.g., when testing redirects or HTML endpoints)
• Use makeAuthorizationCode() for generating OAuth test codes

Common mistake: Using raw fetch instead of the configured utilities.

// ✅ Good - Use configured utilities
import { api, apiFetch } from "./test-utils";

// For JSON API calls
const { data } = await api.GET("/my/endpoint");

// For raw HTTP (redirects, HTML)
const response = await apiFetch.raw("/my/endpoint", { redirect: "manual" });

// ❌ Bad - Using raw fetch
const response = await fetch("/my/endpoint");

2. Avoid Code Duplication

Before creating new functions or components:

1. Search the codebase for similar functionality
2. Consider extracting common patterns into reusable utilities
3. Check if existing functions can be parameterized instead of duplicated

Common mistake: Creating duplicate HTML generation or similar logic without checking for existing implementations.

3. Write Clean, Focused Tests

Follow these principles for maintainable test code:

Test Architecture Pattern

Tests should follow this layered architecture: Test → Tester → api/apiFetch → services

• Tests should be concise and focus on the behavior being tested
• Tester classes encapsulate all API interactions and provide semantic methods
• api/apiFetch utilities handle HTTP communication
• Services contain the actual business logic

Rule: Tests Should Not Make Direct API Calls

Tests should never call api, apiFetch, or other HTTP utilities directly. Instead, they should use methods from Tester classes.

// ✅ Good - Using Tester methods
test("LINE Login token exchange", async () => {
  const tester = new LineTester();
  const code = tester.getLineLoginAuthorizeCode({ sub: "user123" });
  const result = await tester.exchangeLineLoginCode(code, { 
    client_id: "test_client" 
  });
  expect(result.access_token).toBeDefined();
});

// ❌ Bad - Direct API calls in tests  
test("LINE Login token exchange", async () => {
  const authResponse = await api.POST("/oauth/protocol/openid-connect/token", {
    body: { grant_type: "authorization_code", code: "test" }
  });
  const tokenResponse = await api.POST("/line/oauth2/v2.1/token", {
    body: { grant_type: "authorization_code", code: authResponse.code }
  });
  expect(tokenResponse.access_token).toBeDefined();
});

Keep Tests Concise

• Each test should focus on one specific behavior
• Use descriptive Tester method names that clearly indicate what they do
• If a test is getting long, extract the setup logic into Tester methods

// ✅ Good - Concise test using semantic methods
test("can send message to user", async () => {
  const tester = new LineTester();
  await tester.sendMessage("user123", "Hello!");
  const messages = await tester.getReceivedMessages("user123");
  expect(messages).toHaveLength(1);
  expect(messages[0].text).toBe("Hello!");
});

// ❌ Bad - Long test with implementation details
test("can send message to user", async () => {
  const userId = `user_${Math.random()}`;
  const channelId = `channel_${Math.ran