Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/alinangnaiba/anino

Lightweight .NET mock API server that serves JSON-defined endpoints and forwards unmatched requests to a live backend (YARP) for unified local API during frontend development and testing. Download the tool here https://www.nuget.org/packages/Anino.Tool
https://github.com/alinangnaiba/anino

api-mocking cli devtools dotnet frontend-development http json mock-server reverse-proxy testing yarp

Last synced: 28 days ago
JSON representation

Lightweight .NET mock API server that serves JSON-defined endpoints and forwards unmatched requests to a live backend (YARP) for unified local API during frontend development and testing. Download the tool here https://www.nuget.org/packages/Anino.Tool

Awesome Lists containing this project

README 

          
# Anino - Mock API Server



Anino is a lightweight, fast mock API server that allows you to quickly spin up REST API endpoints from a simple JSON definition file. Perfect for frontend development, testing, and prototyping when you need a backend API that doesn't exist yet. Download in [NuGet](https://www.nuget.org/packages/Anino.Tool)



## Features



- 🚀 **Fast Setup** - Define all your API endpoints in a single JSON file.

- 🔧 **Nested Subcommand Interface** - Clean and clear CLI with `server` and `def new` commands.

- ⚡ **Latency Simulation** - Add artificial delays to simulate real network conditions.

- 🎯 **Custom Status Codes** - Return any HTTP status code you need.

- � **Proxy Pass-Through** - Forward unmatched requests to existing backend servers.

- �📝 **Rich Definition Generator** - Quickly generate a sample definition file with common operations.

- 🛠️ **Cross-Platform** - Runs on Windows, macOS, and Linux.

- 📦 **.NET Global Tool** - Install once, use anywhere.



## Installation



Install Anino as a .NET global tool:



```bash

dotnet tool install -g Anino.Tool

```



### Prerequisites



- .NET 8.0 or .NET 9.0 runtime is required.

- You can check your installed runtimes with `dotnet --list-runtimes`.

- Download .NET from: https://dotnet.microsoft.com/download



## Quick Start



1.  **Generate a sample definition file:**

    The `def new` command creates a `definition.json` file in your current directory.

    ```bash

    anino def new

    ```



2.  **Start the mock server:**

    The `server` command starts the API server using the definition file.

    ```bash

    anino server --def definition.json

    ```



3.  **Test your new API:**

    Open a new terminal and use `curl` or any API client to test the endpoints.

    ```bash

    curl http://localhost:7770/api/users

    curl http://localhost:7770/api/health

    ```



## Command Line Reference



### `anino server`



Starts the Anino mock API server using a JSON definition file.



| Option             | Alias | Description                                      | Required | Default |

| ------------------ | ----- | ------------------------------------------------ | -------- | ------- |

| `--def`            | `-d`  | Path to the JSON definition file.                | Yes      |         |

| `--port`           | `-p`  | The port for the server to listen on.            | No       | `7770`  |

| `--latency`        | `-l`  | Simulated network latency in milliseconds.       | No       | `0`     |

| `--proxy`          | `-pp` | Base URL to forward unmatched requests to.       | No       |         |

| `--use-secure`     | `-us` | Use HTTPS when proxy URL is HTTPS.              | No       | `true`  |



**Examples:**



```bash

# Start server with a required definition file

anino server --def ./api/definition.json



# Start server on a different port with an alias

anino server -d definition.json -p 8080



# Start server with 500ms latency

anino server -d definition.json -l 500



# Start server with HTTP proxy fallback

anino server -d definition.json -pp http://localhost:8000



# Start server with HTTPS proxy (automatically uses HTTPS locally)

anino server -d definition.json -pp https://dev.api.com



# Force HTTP locally while proxying to HTTPS (bypasses SSL validation)

anino server -d definition.json -pp https://dev.api.com --use-secure false



# Combine multiple options

anino server -d definition.json -p 3000 -l 200 -pp https://api.example.com

```



### `anino def new`



Creates a new sample API definition file. This is a subcommand of `def`.



| Option             | Alias | Description                                      | Required | Default          |

| ------------------ | ----- | ------------------------------------------------ | -------- | ---------------- |

| `--name`           | `-n`  | The name of the definition file to be created.   | No       | `definition.json` |



**Examples:**



```bash

# Generate a default definition file named definition.json

anino def new



# Generate a definition file with a custom name

anino def new --name my-api

```



## Sample Definition File



The `anino def new` command creates a file with a structure like this, which you can customize for your needs.



```json

[

  {

    "path": "/api/users",

    "method": "GET",

    "statusCode": 200,

    "response": [

      {

        "id": 1,

        "name": "John Doe",

        "email": "john.doe@example.com"

      }

    ]

  },

  {

    "path": "/api/health",

    "method": "GET",

    "statusCode": 200,

    "response": {

      "status": "healthy",

      "timestamp": "2025-08-21T12:00:00Z"

    }

  }

]

```



## Extending Existing APIs



When working with existing applications, you can use Anino to extend your current API with new mock endpoints while keeping existing functionality intact. This is perfect for testing new features without disrupting your existing backend.



### How It Works



When you specify a `--proxy` URL, Anino acts as a smart proxy that:



1. **Serves mock endpoints** defined in your JSON definition file

2. **Forwards unmatched requests** to your existing backend server

3. **Provides a single entry point** for both mocked and real endpoints



### Example Workflow



Let's say you have an existing API running on `http://localhost:8000` and you want to add new endpoints for testing:



1. **Create a definition file for new endpoints only:**

   ```json

   [

     {

       "path": "/api/new-feature",

       "method": "GET",

       "statusCode": 200,

       "response": {

         "id": 1,

         "feature": "new functionality",

         "enabled": true

       }

     },

     {

       "path": "/api/users",

       "method": "POST",

       "statusCode": 201,

       "response": {

         "id": 999,

         "name": "Test User",

         "created": true

       }

     }

   ]

   ```



2. **Start Anino with proxy enabled:**

   ```bash

   anino server -d new-features.json -pp http://localhost:8000

   ```



3. **Use a single URL for everything:**

   ```bash

   # These requests go to your new mock endpoints

   curl http://localhost:7770/api/new-feature

   curl -X POST http://localhost:7770/api/users -d '{"name":"Test"}'

   

   # These requests are forwarded to your existing API

   curl http://localhost:7770/api/existing-users

   curl http://localhost:7770/api/products

   ```



### Benefits



- **No configuration changes** in your frontend application

- **Seamless testing** of new features alongside existing ones

- **Override existing endpoints** when needed for testing scenarios

- **Single development workflow** regardless of backend availability



## HTTPS and SSL Handling



Anino automatically handles HTTPS scenarios to make development seamless:



### Automatic HTTPS Detection



When you specify an HTTPS proxy URL, Anino automatically runs your mock server on HTTPS to match:



```bash

# This automatically starts the mock server on https://localhost:7770

anino server -d api.json -pp https://dev.api.com

```



### Handling HTTPS & SSL Certificates



Proxying to HTTPS endpoints can present certificate validation issues. Here’s how to handle the two most common scenarios.



#### Scenario 1: Proxying to `localhost`

When proxying to a local service (e.g., `https://localhost:5001`), your machine might not trust the .NET development certificate.



✅ The Fix: The best practice is to explicitly trust the local dev certificate. Run this command once in your terminal:

```bash

dotnet dev-certs https --trust

```



#### Scenario 2: Proxying to a Dev Server with an Untrusted Certificate

When proxying to a non-production API (e.g., `https://dev.api.com`), you may get an SSL error. This happens because the server is using a certificate that isn't trusted by your machine, such as a self-signed certificate or one from an internal company Certificate Authority (CA).



##### Method 1: The Quick Workaround (Bypass Validation)

For quick tests, you can tell the proxy to ignore SSL validation errors using the `--use-secure false` flag.



```bash

# Runs mock server on HTTP, bypasses SSL validation for proxy requests

anino server -d api.json -pp https://dev.api.com --use-secure false

```



> **⚠️ Security Warning**

> The `--use-secure false` flag disables all SSL certificate checks, making the connection vulnerable to **Man-in-the-Middle (MitM) attacks**. This feature is for trusted development environments only. **NEVER use this flag when proxying to a production API.**



##### Method 2: The Recommended Solution (Trust the Certificate)



The secure and long-term solution is to configure your machine to trust the certificate authority (CA) used by the dev API.



This usually involves:



1. Obtain the root CA certificate (preferred) or the server’s public certificate (`.cer` or `.pem`).

   - If your team or company provides a custom CA, request the root CA cert from them.

2. Import it into your operating system’s trusted certificate store:

   - **Windows**: Double-click the `.cer` file → *Install Certificate* → *Local Machine* → place it in *Trusted Root Certification Authorities*.

   - **macOS**: Open *Keychain Access* → drag the `.cer` into *System* → mark it as *Always Trust*.

   - **Linux**: Copy the `.cer` into `/usr/local/share/ca-certificates/` → run `sudo update-ca-certificates`.



Once trusted, your proxy will connect without needing the `--use-secure false` flag.



> ⚠️ **Note**: Only trust certificates that come from your team/company. Do not install arbitrary or unverified certificates. And only add them on your **development machine**—never on production servers.



### Protocol Matching Examples



```bash

# HTTP proxy → HTTP mock server

anino server -d api.json -pp http://localhost:3000

# → Mock server: http://localhost:7770



# HTTPS proxy → HTTPS mock server (default)

anino server -d api.json -pp https://api.example.com

# → Mock server: https://localhost:7770



# HTTPS proxy → HTTP mock server (SSL bypass enabled)

anino server -d api.json -pp https://api.example.com --us false -p 3000

# → Mock server: http://localhost:3000 (with SSL bypass warning)

```