Introducing @arkarmintun/api-mocker: A Directory-Based API Mocking Solution

In today's fast-paced development environment, frontend developers often find themselves blocked waiting for backend APIs to be completed. This is where @arkarmintun/api-mocker comes in - a lightweight, flexible tool designed to simplify API mocking through a file system-based approach.

What is @arkarmintun/api-mocker?

@arkarmintun/api-mocker is a simple, directory-based API mock server that serves JSON responses for your frontend development and testing needs. Unlike other mocking solutions that rely on complex configuration files or code-based setups, this package embraces a more intuitive file system approach that mirrors your actual API structure.

Key Features

📁 Directory-Based Organization

One of the most compelling features of @arkarmintun/api-mocker is its directory-based organization system. By structuring your mock responses in folders that mirror your actual API endpoints, you create an intuitive, visual representation of your API. This approach makes it easy to understand, maintain, and update your mock API as your real API evolves.

🔄 Support for All HTTP Methods

The package supports all standard HTTP methods, including GET, POST, PUT, DELETE, and more. This ensures you can mock your entire API, regardless of the complexity of your endpoints or the variety of methods they use.

🔍 Dynamic Path Parameters

Creating mock responses for endpoints with dynamic parameters is made simple through the [paramName] directory naming convention. This allows you to simulate endpoints like /users/[id] or /products/[category]/[id] without writing any code.

📦 Plain JSON Responses

No need to write complex JavaScript code to generate responses - simply create JSON files that contain the exact response you want to return. These files are served as-is, making it easy to maintain and update your mock responses.

🚨 Interactive Error Testing

With the interactive CLI, you can easily simulate error scenarios to test how your frontend application handles API errors. This helps ensure your application is robust and can gracefully handle unexpected responses.

⏱️ Network Delay Simulation

Simulate real-world network conditions by adding configurable delays to your API responses. This is particularly useful for testing loading states and ensuring your application remains responsive even under suboptimal network conditions.

🔄 CORS Support

Built-in CORS support allows you to test your frontend application across different origins without running into cross-origin restrictions.

🚀 Easy Setup and Use

Getting started with @arkarmintun/api-mocker is straightforward, with minimal configuration required.

Installation

You can install @arkarmintun/api-mocker globally:

npm install -g @arkarmintun/api-mocker

Or use it directly with npx:

npx @arkarmintun/api-mocker --init

Getting Started

Basic Setup

Initialize a new project

The following command will create mock folder with some example JSON content. You can use or remove those files if you want to.

npx @arkarmintun/api-mocker --init

Start the mock server

npx @arkarmintun/api-mocker

Create JSON response files

Add your mock response data to the JSON files. For example, in mocks/api/users/GET.json:

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "email": "jane@example.com"
  }
]

Create your directory structure

Create a directory structure that mirrors your API endpoints. For example:

mocks/
├── users/
│   ├── GET.json           # GET /api/users
│   ├── POST.json          # POST /api/users
│   └── [id]/
│       ├── GET.json       # GET /api/users/:id
│       ├── PUT.json       # PUT /api/users/:id
│       └── DELETE.json    # DELETE /api/users/:id
└── products/
    ├── GET.json           # GET /api/products
    └── [id]/
        └── GET.json       # GET /api/products/:id

Advanced Usage Examples

Simulating Dynamic Endpoints

Using the [paramName] directory naming convention, you can create dynamic endpoints:

mock/
├── users/
│   └── [id]/
│       └── GET.json       # GET /api/users/:id

The GET.json file might contain:

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin"
}

When a request is made to /api/users/1 or /api/users/42, this response will be returned.

Testing Error Scenarios

You can create specific error responses by adding status codes to your file names:

mocks/
├── users/
│   └── [id]/
│       ├── GET.json           # 200 response
│       └── GET_404.json       # 404 response for not found

Simulating Network Delays

You can simulate network delays by adding a configuration when running the project

npx @arkarmintun/api-mocker -D 5000

or

npx @arkarmintun/api-mocker --delay 5000

Best Practices

1. Mirror your API structure: Create a directory structure that exactly mirrors your actual API endpoints.
2. Use realistic data: Populate your mock responses with realistic data to better simulate the real API.
3. Test error cases: Create variations of your responses with different status codes to test how your application handles errors.
4. Version control your mocks: Include your mock directory in your version control system so your team can share consistent mock data.
5. Document your mock API: Maintain documentation for your mock API, especially if you have complex mock responses or specific testing scenarios.

Conclusion

@arkarmintun/api-mocker provides a simple yet powerful approach to API mocking using a directory-based structure. By organizing your mock responses in folders that mirror your API endpoints, you create an intuitive, maintainable mock API that can evolve alongside your real API.

Whether you're working on a new project that doesn't yet have a backend, or you're developing against an existing API that isn't always available, @arkarmintun/api-mocker helps you maintain development velocity without backend dependencies.

Try it out today and experience the simplicity and power of directory-based API mocking!

For the most up-to-date information, visit the GitHub repository or the npm package page.