apicentric-0.2.3 has been yanked.

Apicentric

A powerful CLI tool and API simulator platform for developers who love the terminal

https://apicentric.pelayomaojo.es

What is Apicentric?

Apicentric is a Rust-based CLI tool and API simulator platform that helps developers:

🎯 Mock APIs with simple YAML configuration
✅ Test API contracts between services
🔄 Generate code (TypeScript types, React Query hooks)
✨ MCP Power your agent with API mocking tools
🖥️ TUI (Terminal User Interface) for visual service management
🌐 P2P collaboration on service definitions (optional)

Perfect for frontend developers who need backend APIs, teams doing contract testing, or anyone who loves working in the terminal.

Core Concepts

Apicentric is built around a few core concepts:

Service Definition: A YAML file that defines a mock API, including its endpoints, responses, and scenarios.
Simulator: A local server that serves the mock APIs defined in your service definitions.
Contract Testing: A feature that allows you to validate that your mock APIs match the real APIs they are mocking.
Code Generation: A feature that allows you to generate client code from your service definitions.
TUI: A terminal user interface that provides a visual way to manage your services.

Real-World Example: E-commerce API

Let's simulate a realistic e-commerce API with dynamic data, request validation, and multiple scenarios.

1. Create the Service Definition

Create a file named ecommerce-api.yaml with the following content:

name: E-commerce API
version: "2.1"
description: Sample e-commerce API with products and orders
server:
  port: 9002
  base_path: /api/v2

fixtures:
  products:
    - id: 101
      name: "Laptop Pro"
      price: 1299.99
      category: "electronics"
      stock: 15
    - id: 102
      name: "Coffee Mug"
      price: 12.50
      category: "home"
      stock: 50

endpoints:
  - method: GET
    path: /products
    description: List products with optional filtering
    parameters:
      - name: category
        in: query
        required: false
        type: string
    responses:
      200:
        content_type: application/json
        body: |
          {
            "products": [
              {{#each fixtures.products}}
              {
                "id": {{id}},
                "name": "{{name}}",
                "price": {{price}},
                "category": "{{category}}",
                "stock": {{stock}}
              }{{#unless @last}},{{/unless}}
              {{/each}}
            ],
            "total": {{fixtures.products.length}},
            "filter": "{{query.category}}"
          }

  - method: POST
    path: /orders
    description: Create a new order
    request_body:
      content_type: application/json
      schema: |
        {
          "customer_id": "number",
          "items": [{"product_id": "number", "quantity": "number"}]
        }
    responses:
      201:
        content_type: application/json
        body: |
          {
            "order_id": {{faker "datatype.number" min=1000 max=9999}},
            "customer_id": {{request.body.customer_id}},
            "items": {{json request.body.items}},
            "total": {{faker "commerce.price"}},
            "status": "pending",
            "created_at": "{{now}}"
          }
      422:
        condition: "{{not request.body.customer_id}}"
        content_type: application/json
        body: |
          {
            "error": "Invalid order",
            "details": ["Customer ID is required"]
          }

  - method: GET
    path: /orders/{id}/status
    description: Get order status
    responses:
      200:
        content_type: application/json
        body: |
          {
            "order_id": {{params.id}},
            "status": "{{#random}}pending,processing,shipped,delivered{{/random}}",
            "updated_at": "{{now}}"
          }

scenarios:
  - name: "holiday_traffic"
    description: "Simulate high traffic during holidays"
    delay_ms: 1500
    response_rate: 0.8

  - name: "maintenance_mode"
    description: "Service under maintenance"
    response:
      status: 503
      headers:
        Retry-After: "3600"
      body: |
        {
          "error": "Service under maintenance",
          "retry_after": "1 hour"
        }

2. Start the Simulator

Run the following command in your terminal:

apicentric simulator start --services-dir .

Apicentric will start a server on port 9002.

3. Interact with the API

Now you can send requests to your mock API:

Get all products:

curl http://localhost:9002/api/v2/products

Create a new order:

curl -X POST http://localhost:9002/api/v2/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 12345,
    "items": [
      {"product_id": 101, "quantity": 1},
      {"product_id": 102, "quantity": 2}
    ]
  }'

Get order status:

curl http://localhost:9002/api/v2/orders/5678/status

This example demonstrates features like:

Fixtures: Reusable data for your endpoints.
Dynamic Responses: Handlebars templating for realistic data.
Request Validation: Conditional responses based on the request body.
Scenarios: Simulate different API states like high traffic or maintenance.

4. Dockerize the Service

Create a portable Docker image for your service:

apicentric simulator dockerize --services ecommerce-api.yaml --output ./ecommerce-docker

This will create a Dockerfile and copy the service definition into the ecommerce-docker directory. You can then build and run the image:

cd ecommerce-docker
docker build -t ecommerce-api .
docker run -p 9002:9002 ecommerce-api

Installation

Apicentric provides multiple installation methods to suit your workflow. Choose the one that works best for you.

Homebrew (macOS/Linux) - Recommended

The easiest way to install on macOS and Linux:

brew install pmaojo/tap/apicentric

Verify installation:

apicentric --version

Update to latest version:

brew upgrade apicentric

Install Script (Unix)

Quick installation script for Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/pmaojo/apicentric/main/scripts/install.sh | sh

This script will:

Detect your platform and architecture automatically
Download the appropriate binary
Verify checksums for security
Install to /usr/local/bin (requires sudo)

Custom installation directory:

INSTALL_DIR=$HOME/.local/bin curl -fsSL https://raw.githubusercontent.com/pmaojo/apicentric/main/scripts/install.sh | sh

Verify installation:

apicentric --version

Windows PowerShell

For Windows users, use the PowerShell installation script:

irm https://raw.githubusercontent.com/pmaojo/apicentric/main/scripts/install.ps1 | iex

This script will:

Download the Windows x64 binary
Verify checksums
Extract to %USERPROFILE%\.apicentric\bin
Add to PATH (restart terminal after installation)

Verify installation:

apicentric --version

Cargo (Build from Source)

If you have Rust installed, you can build from source with custom features:

Minimal build (fastest, ~1 minute):

cargo install apicentric --no-default-features --features minimal

Includes: Core simulator only

CLI Tools build (recommended, ~2 minutes):

cargo install apicentric --features cli-tools

Includes: Simulator, contract testing, and TUI

Full build (all features, ~3-5 minutes):

cargo install apicentric --features full

Includes: All features (TUI, P2P, GraphQL, scripting, AI)

Default build:

cargo install apicentric

Includes: Simulator and contract testing

Verify installation:

apicentric --version

Pre-built Binaries

Download pre-built binaries for your platform from GitHub Releases.

Available platforms:

Linux x64 (apicentric-linux-x64.tar.gz)
macOS x64 (apicentric-macos-x64.tar.gz)
macOS ARM64 (apicentric-macos-arm64.tar.gz)
Windows x64 (apicentric-windows-x64.zip)

Manual installation (Linux/macOS):

# Download the appropriate archive
curl -LO https://github.com/pmaojo/apicentric/releases/latest/download/apicentric-linux-x64.tar.gz

# Verify checksum (optional but recommended)
curl -LO https://github.com/pmaojo/apicentric/releases/latest/download/checksums.txt
sha256sum -c checksums.txt --ignore-missing

# Extract
tar -xzf apicentric-linux-x64.tar.gz

# Move to PATH
sudo mv apicentric /usr/local/bin/

# Make executable
sudo chmod +x /usr/local/bin/apicentric

Manual installation (Windows):

Download apicentric-windows-x64.zip from releases
Extract the archive
Move apicentric.exe to a directory in your PATH
Or add the directory to your PATH environment variable

Verify installation:

apicentric --version

Docker

You can use the dockerize command to create a self-contained Docker image for your services.

apicentric simulator dockerize --services <service1>.yaml [<service2>.yaml ...] --output ./my-service-docker

This will generate a Dockerfile and a .dockerignore file in the output directory, along with a services directory containing your service definitions.

You can then build and run the image:

cd my-service-docker
docker build -t my-service .
docker run -p <port>:<port> my-service

Verification

After installation, verify that Apicentric is working correctly:

# Check version
apicentric --version

# View help
apicentric --help

# List available commands
apicentric simulator --help

Expected output should show version information and available commands.

Troubleshooting

Command not found

Issue: apicentric: command not found after installation

Solutions:

Homebrew: Ensure Homebrew's bin directory is in your PATH:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc

Install script: Verify /usr/local/bin is in your PATH:

echo $PATH | grep -q "/usr/local/bin" && echo "✓ In PATH" || echo "✗ Not in PATH"

Windows: Restart your terminal or PowerShell after installation to refresh PATH

Cargo: Ensure ~/.cargo/bin is in your PATH:

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Permission denied

Issue: Permission errors during installation

Solutions:

Unix install script: The script requires sudo for /usr/local/bin. Use custom directory:

INSTALL_DIR=$HOME/.local/bin curl -fsSL https://raw.githubusercontent.com/pmaojo/apicentric/main/scripts/install.sh | sh

Then add to PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Manual installation: Use sudo when moving to system directories:

sudo mv apicentric /usr/local/bin/
sudo chmod +x /usr/local/bin/apicentric

Checksum verification failed

Issue: Checksum mismatch during installation

Solutions:

Download may be corrupted. Delete and try again:

rm apicentric-*.tar.gz
curl -LO https://github.com/pmaojo/apicentric/releases/latest/download/apicentric-linux-x64.tar.gz

Verify you're downloading from the official repository
Check your internet connection

Cargo build fails

Issue: Compilation errors when building from source

Solutions:

Update Rust: Ensure you have the latest stable Rust:
```
rustup update stable
```
Missing dependencies: Install required system dependencies:
- Ubuntu/Debian:
```
sudo apt-get update
sudo apt-get install build-essential pkg-config libssl-dev
```
- macOS:
```
xcode-select --install
```
- Windows: Install Visual Studio Build Tools

Try minimal build: If full build fails, try minimal:

cargo install apicentric --no-default-features --features minimal

Feature not available

Issue: Command shows "Feature not available in this build"

Solutions:

You installed a minimal build. Reinstall with desired features:
```
cargo install apicentric --features cli-tools --force
```

Or install full version:

brew reinstall apicentric  # Homebrew includes cli-tools features

macOS security warning

Issue: "apicentric cannot be opened because it is from an unidentified developer"

Solutions:

Option 1: Use Homebrew installation (recommended):
```
brew install pmaojo/tap/apicentric
```

Option 2: Allow the binary manually:

xattr -d com.apple.quarantine /usr/local/bin/apicentric

Option 3: Build from source with Cargo:

cargo install apicentric --features cli-tools

Still having issues?

If you're still experiencing problems:

Check GitHub Issues for similar problems
Create a new issue with:
- Your operating system and version
- Installation method used
- Complete error message
- Output of apicentric --version (if available)
Join our Discussions for community support

Features

🎯 API Simulator

Define mock APIs in YAML and serve them locally:

Path parameters and regex matching
Dynamic templates with Handlebars
Scenarios for different states
Request/response logging
Request recording proxy and auto-generated endpoints via record_unknown
Import from various formats like OpenAPI, Postman, WireMock, and Mockoon with apicentric simulator import.

GraphQL Mocking

Define GraphQL mocks with a schema and response templates.
Create a new GraphQL service from scratch with apicentric simulator new-graphql <name>.

🐳 Dockerize Services

Package your mock services into self-contained Docker images for easy deployment and sharing.

Generate a Dockerfile for one or more services.
Exposes all service ports automatically.
Creates a portable image that can be run anywhere.

✅ Contract Testing

Validate that mocks match real APIs:

Register contracts from specs
Compare mock vs real responses
HTML reports with differences
CI/CD integration

🔄 Code Generation & Exporting

Generate client code from service definitions or export to standard formats:

Generate TypeScript types: apicentric simulator generate-types
Generate React Query hooks: apicentric simulator generate-query
Export to OpenAPI: apicentric simulator export --format openapi
Export to Postman: apicentric simulator export --format postman

🖥️ TUI (Terminal User Interface)

Interactive terminal dashboard for service management:

Real-time service status
Live request logs with filtering
Start/stop services
Keyboard-driven workflow

🤖 AI Integration with MCP (Model Context Protocol)

Apicentric supports the Model Context Protocol (MCP), allowing AI assistants like Claude, ChatGPT, and other MCP-compatible tools to interact with your API simulator programmatically.

What is MCP?

MCP is an open protocol that enables AI models to securely access external tools and data sources. With MCP, AI assistants can:

Create and manage mock API services
Start/stop services dynamically
Monitor service logs and status
Generate service definitions from natural language descriptions

Quick MCP Setup

Install with MCP support:

cargo install apicentric --features mcp
# or
brew install pmaojo/tap/apicentric  # includes MCP

Configure your AI assistant:

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "apicentric": {
      "command": "apicentric",
      "args": ["mcp"]
    }
  }
}

For VS Code (.vscode/mcp.json):

{
  "servers": {
    "apicentric": {
      "type": "stdio",
      "command": "apicentric",
      "args": ["mcp"]
    }
  }
}

Start using MCP tools in your AI assistant:
```
"Create a mock API for a user management system with login and profile endpoints"
```
The AI will use MCP tools to automatically create and start the service!

Available MCP Tools

list_services: List all available mock services
create_service: Create a new service from YAML definition
start_service: Start a specific mock service
stop_service: Stop a running service
get_service_logs: Retrieve logs for a service

MCP Example Workflow

User: "Create a REST API for managing books with CRUD operations"

AI Assistant (using MCP tools):

Uses create_service to generate a books API YAML
Uses start_service to launch the API on a port
Confirms with get_service_logs that it's running
Provides curl examples for testing

Result: A fully functional mock API ready for testing!

MCP Benefits

Natural Language API Creation: Describe your API in plain English
Automated Testing Setup: AI handles service creation and configuration
Integrated Development: Seamless workflow between AI assistance and API development
Rapid Prototyping: Go from idea to working mock API in seconds

🌐 Advanced Features (Optional)

P2P Collaboration: Share services with team members
GraphQL Mocking: Mock GraphQL APIs with schema
JavaScript Plugins: Extend with custom logic

Documentation

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Community

Crate Modules

The crate follows hexagonal architecture principles and exposes the following modules:

app: Application bootstrap and command execution.
config: Configuration management for the simulator and tooling.
context: Shared runtime context and dependency wiring.
errors: Custom error types aligned with domain-driven design.
logging: Logging setup and tracing utilities.
utils: Cross-cutting helper functions.
validation: Input validation helpers used across adapters and domain logic.
storage: Persistence adapters for service specifications.
ai: AI-assisted tooling integrations.
cloud: Cloud synchronization utilities.
auth: Authentication helpers for collaborative scenarios.
domain: Core business rules and ports.
contract: Contract testing orchestration.
adapters: Infrastructure adapters that implement ports.
simulator: The API simulator runtime.
cli and cli_ui: CLI and text-based UI front-ends.

Refer to the module documentation for deeper implementation details.

apicentric 0.2.3

Apicentric

What is Apicentric?

Core Concepts

Real-World Example: E-commerce API

1. Create the Service Definition

2. Start the Simulator

3. Interact with the API

4. Dockerize the Service

Installation

Homebrew (macOS/Linux) - Recommended

Install Script (Unix)

Windows PowerShell

Cargo (Build from Source)

Pre-built Binaries

Docker

Verification

Troubleshooting

Command not found

Permission denied

Checksum verification failed

Cargo build fails

Feature not available

macOS security warning

Still having issues?

Features

🎯 API Simulator

GraphQL Mocking

🐳 Dockerize Services

✅ Contract Testing

🔄 Code Generation & Exporting

🖥️ TUI (Terminal User Interface)

🤖 AI Integration with MCP (Model Context Protocol)

What is MCP?

Quick MCP Setup

Available MCP Tools

MCP Example Workflow

MCP Benefits

🌐 Advanced Features (Optional)

Documentation

Contributing

License

Community

Crate Modules