Crate apicentric

Expand description

§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)
🖥️ 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

§🌐 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.

Re-exports§

pub use config::ApicentricConfig;
pub use context::Context;
pub use context::ContextBuilder;
pub use context::ExecutionContext;
pub use errors::ApicentricError;
pub use errors::ApicentricResult;
pub use simulator::ApiSimulatorManager;
pub use simulator::ServiceDefinition;
pub use simulator::SimulatorConfig;
pub use domain::contract_testing::*;
pub use domain::contract::*;
pub use infrastructure::*;

Modules§

adapters
ai: Provides a common interface for AI providers.
app: Manages dynamically loaded plugins and executes their hooks.
auth: Authentication and authorization.
cli: The command-line interface for apicentric.
cli_ui: Manages the command-line user interface, providing functions for printing banners, status messages, progress bars, and formatted text to the console. It uses the colored, console, and indicatif crates to enhance the visual presentation of output.
cloud: The cloud API.
config
context
contract: Contract testing modules: scenario extraction, execution, and reporting.
domain
env_config
errors: Defines the error types and error handling utilities for the Apicentric application.
infrastructure: Re-exports from the infrastructure layer.
logging: Centralized logging configuration using tracing
mock: Re-export of the mock API facade.
simulator: API Simulator module for Apicentric
storage
utils
validation: Provides validation utilities for configuration objects and common data types.

Macros§

contract_log: Log with structured fields for contract operations
debug_lazy: Performance-optimized debug logging that only evaluates arguments when debug is enabled
log_structured: Macro for structured logging
request_span: Create a span for request handling
service_span: Create a span for service operations
simulator_log: Log simulator events with structured data

Functions§

greet: A simple example function exposed to WebAssembly consumers.