DEV Community: Air Pipe

How to build your own MCP server

Kav Pather — Tue, 04 Aug 2026 17:05:00 +0000

Most MCP tutorials hand you a Node project. You install an SDK, write a tool
handler, wire up stdio, and end up with something that runs on your laptop as
you, with your credentials, for exactly one user.

That's fine for a demo. It's not something you can give a customer.

Here's the other way, end to end: a database, one config file, a token, and a
URL you paste into Claude. Every step below is a real command against a real
pack — nothing elided, nothing left as an exercise.

Time: about 15 minutes. You'll need: an Air Pipe account (free tier is
enough), a Postgres database, and an MCP client — Claude Desktop, Claude Code,
Cursor, anything that speaks MCP.

Step 1 — Get a Postgres database

If you already have one, skip ahead. If not, any of these work and all have a
usable free tier:

Provider	What you get
Neon	Serverless Postgres, free tier, connection string in the dashboard
Supabase	Postgres + a UI to browse rows while you test
Local	`docker run -e POSTGRES_PASSWORD=pw -p 5432:5432 postgres:16`

What you need out of it is one connection string:

postgresql://user:password@host:5432/dbname

A local Postgres works for following along, but your managed Air Pipe instance
can't reach localhost — so if you want the tools live from Claude Desktop, use
a hosted database or self-host the Air Pipe binary next to your local one.

On SSL: most hosted providers require it. If your first query fails with
SSL is required, append ?sslmode=require to the connection string. Neon
needs this; Supabase includes it in the string it gives you.

Step 2 — Create the schema

Three tables. Only one of them is your data:

CREATE EXTENSION IF NOT EXISTS pgcrypto;

-- A tenant is one of YOUR customers. Ignore it entirely while it's just you;
-- it's what makes step 8 possible without a rewrite.
CREATE TABLE IF NOT EXISTS mcp_tenants (
  id         UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
  name       TEXT        NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Issued token metadata — the revocation denylist. The token string itself is
-- never stored, only its jti claim.
CREATE TABLE IF NOT EXISTS mcp_tokens (
  jti        UUID        PRIMARY KEY,
  tenant_id  UUID        NOT NULL REFERENCES mcp_tenants(id) ON DELETE CASCADE,
  subject    TEXT        NOT NULL,
  name       TEXT        NOT NULL DEFAULT 'default',
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  expires_at TIMESTAMPTZ NOT NULL,
  revoked_at TIMESTAMPTZ
);

-- The resource your tools read and write. Swap this for your own table.
CREATE TABLE IF NOT EXISTS mcp_tasks (
  id         UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id  UUID        NOT NULL REFERENCES mcp_tenants(id) ON DELETE CASCADE,
  title      TEXT        NOT NULL,
  status     TEXT        NOT NULL DEFAULT 'open' CHECK (status IN ('open', 'done')),
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_mcp_tasks_tenant ON mcp_tasks (tenant_id, created_at DESC);

Run it:

psql "$DATABASE_URL" -f schema.sql

pgcrypto is only needed for gen_random_uuid() on Postgres 12 and earlier —
it's built in from 13 on, and the IF NOT EXISTS makes the line harmless either
way.

Seed a tenant and a couple of rows so there's something to see:

INSERT INTO mcp_tenants (id, name)
VALUES ('11111111-1111-1111-1111-111111111111', 'Acme Inc');

INSERT INTO mcp_tasks (tenant_id, title, status) VALUES
  ('11111111-1111-1111-1111-111111111111', 'Ship the MCP launch post', 'open'),
  ('11111111-1111-1111-1111-111111111111', 'Review Q3 numbers',        'done');

Step 3 — Set two variables

In the Air Pipe dashboard, under your environment's managed variables (or as
ap_vars if you're self-hosting):

Name	Value
`DATABASE_URL`	the connection string from step 1
`SOLO_SECRET`	a 32+ character random string

Generate the secret rather than typing one — it's the only thing standing
between the internet and your database:

openssl rand -base64 48

Both are referenced as a|ap_var::NAME| in the config, so they never appear in
the file you commit.

Step 4 — Write the config

Here's the whole thing. One file, two tools.

name: McpTasks
description: MCP tools over Postgres, guarded by a single shared HS256 token.

# Who this server says it is when a client calls initialize (engine >= 1.38.0).
mcp_servers:
  tasks:
    title: Tasks
    instructions: >-
      A task list backed by Postgres. Use list_tasks to read tasks (optionally
      filtered to "open" or "done") and create_task to add one. Both tools
      require the bearer token issued by the operator.
    default: true

global:
  databases:
    main:
      driver: postgres
      conn_string: "a|ap_var::DATABASE_URL|"

interfaces:

  # MCP tool: list_tasks   ·   HTTP: POST /solo/tasks
  solo/tasks:
    output: http
    method: POST
    summary: List all tasks
    description: List every task, newest first. Optionally filter by status.
    tags: [tasks]
    mcp:
      enabled: true
      tool_name: list_tasks
      description: List all tasks. Optional status filter ("open" or "done").

    actions:
      - name: ValidateToken
        input: a|headers|
        hide_data_on_success: true
        assert:
          http_code_on_error: 401
          error_message: "Invalid or missing token"
          tests:
            - value: airpipe-jwt
              is_not_null: true
              is_valid_jwt: a|ap_var::SOLO_SECRET|
        post_transforms:
          - extract_value: jwt_claims

      - name: CheckBody
        run_when_succeeded:
          actions: [ValidateToken]
          http_code_on_error: 400
        input: a|body|
        hide_data_on_success: true
        assert:
          tests:
            - value: status
              is_not_null: false
              description: Optional status filter — "open" or "done".

      - name: ListTasks
        run_when_succeeded: [CheckBody]
        database: main
        query: |
          SELECT id, title, status, created_at
          FROM mcp_tasks
          WHERE ($1::text IS NULL OR status = $1::text)
          ORDER BY created_at DESC
          LIMIT 200;
        params:
          - a|body::status->default(null)|

  # MCP tool: create_task   ·   HTTP: POST /solo/tasks/create
  solo/tasks/create:
    output: http
    method: POST
    summary: Create a task
    tags: [tasks]
    mcp:
      enabled: true
      tool_name: create_task
      description: Create a new task. Requires a title; status defaults to "open".

    actions:
      - name: ValidateToken
        input: a|headers|
        hide_data_on_success: true
        assert:
          http_code_on_error: 401
          error_message: "Invalid or missing token"
          tests:
            - value: airpipe-jwt
              is_not_null: true
              is_valid_jwt: a|ap_var::SOLO_SECRET|

      - name: CheckBody
        run_when_succeeded:
          actions: [ValidateToken]
          http_code_on_error: 400
        input: a|body|
        hide_data_on_success: true
        assert:
          http_code_on_error: 400
          error_message: "title is required"
          tests:
            - value: title
              is_not_null: true
              is_not_empty: true
              description: The task title.
            - value: status
              is_not_null: false
              description: Optional status — "open" (default) or "done".

      - name: CreateTask
        run_when_succeeded: [CheckBody]
        database: main
        query: |
          INSERT INTO mcp_tasks (tenant_id, title, status)
          VALUES ($1::uuid, $2, COALESCE($3, 'open'))
          RETURNING id, title, status, created_at;
        params:
          - "11111111-1111-1111-1111-111111111111"
          - a|CheckBody::title|
          - a|body::status->default(null)|
        post_transforms:
          - extract_value: "[0]"

Five things worth pointing at:

mcp_servers is the server; mcp: blocks are the tools. The declaration at
the top is what a client and a registry see before any tool runs — more on it
after step 8. Delete it and everything still works, just anonymously.

The mcp: block is the only thing that makes it a tool. Delete it and you
have an ordinary HTTP route. Keep it and you have both — same auth, same query,
same trace, one definition.

Auth is not MCP-specific. Air Pipe takes the client's
Authorization: Bearer token, forwards it into the interface as the
airpipe-jwt header, and runs the same actions an HTTP request would.
Securing an MCP tool is exactly securing a route. One model to learn, not
two.

CheckBody is what the AI sees. The MCP inputSchema is generated from
those assert tests — which is why each carries a description:. Write them for
a reader who isn't you, because the model picks tools by reading them.
is_not_null: false is an always-pass predicate: it declares the field as
optional without requiring it. And because only CheckBody reads a|body|,
the token never leaks into the tool's schema.

Parameters are bound, not interpolated. $1, $2 with a params: list —
so a task titled '); DROP TABLE mcp_tasks; -- is a task title.

Step 5 — Deploy

Nothing to build and nothing to host.

On managed Air Pipe, paste the file into the dashboard editor and hit deploy —
that validates it on the way in. If you're using the Air Pipe MCP tools from
your own AI client, "validate and deploy this config" does the same from the
chat, and installing the pack (below) does it without either.

Self-hosting is one command — point the binary at the directory holding the
file:

airpipe server --config-dir . --api-key <your-key>

It serves on port 4111 by default, so the URLs in the next steps are
http://localhost:4111/…. Run airpipe login once and you can drop
--api-key.

Step 6 — Mint a token

Once, at jwt.io: algorithm HS256, secret = your
SOLO_SECRET, payload:

{ "sub": "me", "exp": 1798761600 }

Copy the token. Rotating SOLO_SECRET invalidates it.

Prefer the command line:

python3 - <<'PY'
import base64, hmac, hashlib, json, os
def b64(b): return base64.urlsafe_b64encode(b).rstrip(b'=')
secret = os.environ['SOLO_SECRET'].encode()
msg = b64(json.dumps({"alg":"HS256","typ":"JWT"}).encode()) + b'.' + \
      b64(json.dumps({"sub":"me","exp":1798761600}).encode())
sig = b64(hmac.new(secret, msg, hashlib.sha256).digest())
print((msg + b'.' + sig).decode())
PY

Step 7 — Verify it before you touch the client

Debugging through an MCP client is miserable — a failure shows up as "the tool
didn't work." Check with curl first. MCP is JSON-RPC over HTTP, so you can
drive it directly:

BASE=https://your-airpipe-host/<org>/<env>   # self-hosted: no /<org>/<env>
TOKEN=<the token from step 6>

# List the tools
curl -sX POST $BASE/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'
# → "list_tasks"
# → "create_task"

# Call one
curl -sX POST $BASE/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"create_task","arguments":{"title":"Draft the changelog"}}}'

# The same tool over plain HTTP — note the header name changes
curl -sX POST $BASE/solo/tasks \
  -H "airpipe-jwt: $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"status":"open"}' | jq '.data.ListTasks.data'

If tools/list returns your two tools and tools/call returns a row, you're
done — everything after this is client configuration.

Two failures worth naming, because they're the common ones:

401 Invalid or missing token — the secret used to sign doesn't match SOLO_SECRET, or exp is in the past. Decode the token at jwt.io and check the expiry first; it's usually that.
A database error on the query action — the connection string can't be reached from your Air Pipe instance. localhost is the usual culprit, SSL the other.

Step 8 — Point Claude at it

{
  "mcpServers": {
    "my-tasks": {
      "url": "https://your-airpipe-host/<org>/<env>/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Claude Desktop keeps this at
~/Library/Application Support/Claude/claude_desktop_config.json on macOS and
%APPDATA%\Claude\claude_desktop_config.json on Windows. Claude Code:
claude mcp add --transport http my-tasks https://your-airpipe-host/<org>/<env>/mcp --header "Authorization: Bearer <token>".

Restart the client. Ask "what's on my task list?" and it queries your
database.

You also have, from that same file and with no extra work: an HTTP endpoint for
the clients that don't speak MCP, OpenAPI docs, Prometheus metrics, and an
OpenTelemetry trace for every tool call showing which action ran and how long
the query took. That last one matters more than it sounds — when a model calls
a tool and gets a confusing answer, the trace is how you find out whether the
tool was wrong or the model was.

Give the server a name, not just tools

Every client calls initialize before it lists anything, and that response is
where the server says who it is. Skip it and yours introduces itself with a
built-in name and no description — a listing that's a bare label above a wall of
tool descriptions. That's what mcp_servers at the top of the config fixes:

mcp_servers:
  tasks:
    title: Tasks               # -> serverInfo.title, the name in the client's UI
    instructions: >-           # -> the initialize result's `instructions`
      A task list backed by Postgres. Use list_tasks to read tasks and
      create_task to add one. Both require the operator's bearer token.
    default: true              # adopt every tool that names no server

instructions matters more than it looks. MCP registries — mcp.so, Glama,
Smithery, PulseMCP — read a remote server's listing description straight off
that field. There is no other place to write one, so an unlisted description
isn't a blank field somewhere; it's a listing nobody clicks.

Check it the same way you checked the tools:

curl -sX POST $BASE/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1"}}}' \
  | jq '{title: .result.serverInfo.title, instructions: .result.instructions}'

Declaring a server and contributing tools to it are separate on purpose. An
MCP server is a named group of tools, not a property of one config: tools in
any of your configs join a server by id, so one identity can cover tools spread
across many files — which also means the declaration can live alone in its own
config (interfaces: {}) and survive whichever tool file you rename next.

The id is a route segment, so a second declaration is a second endpoint from the
same deployment — a public server and an internal one, say:

mcp_servers:
  tasks:                       # served at /mcp
    title: Tasks
    default: true
  tasks-admin:                 # served at /mcp/tasks-admin
    title: Tasks (admin)

    mcp:
      enabled: true
      tool_name: purge_tasks
      server: tasks-admin      # published only on the named endpoint

Ids are 1–64 characters of a-z, 0-9 or -, only one server may be the
default, and a tool naming a server nothing declares publishes on no server
rather than the wrong one. Needs engine ≥ 1.38.0.

The hole most MCP servers have

Worth knowing regardless of what you build with: tools/call runs your code,
tools/list doesn't.

Listing tools returns metadata — names, descriptions, input schemas. Whatever
auth you put inside your handlers never fires for discovery. So a server with
locked-down calls can still let anyone who knows the URL enumerate every tool
you expose and its full schema. They can't call anything. They can read the map.

For a personal server, fine. For an endpoint you offer customers, that catalog
is often the sensitive part — your tool names are a description of your product.

Close it by adding one line per tool, pointing at an interface that re-runs the
token check when a client lists tools:

    mcp:
      enabled: true
      tool_name: list_tasks
      list_authorizer: authorize-discovery

And the gate itself — an ordinary interface, not a tool:

  authorize-discovery:
    output: http
    method: POST
    summary: Authorize MCP tool discovery for the caller's token.
    tags: [internal]

    actions:
      - name: ValidateToken
        input: a|headers|
        hide_data_on_success: true
        assert:
          http_code_on_error: 401
          error_message: "Invalid or missing token"
          tests:
            - value: airpipe-jwt
              is_not_null: true
              is_valid_jwt: a|ap_var::SOLO_SECRET|
        response_on_success:
          http_code: 200

Now an unauthenticated tools/list returns {"result":{"tools":[]}} — not even
the names.

response_on_success: { http_code: 200 } is required. The gate is
fail-closed on anything that isn't an explicit 2xx, and an interface whose
actions all succeed leaves the status code unset — which reads as "not
authorized" and hides every gated tool even for a valid token. If your tools
vanish after adding the gate, this is why.

Needs engine ≥ 1.7.0. Drop the list_authorizer: line to make discovery public.

Now the part that matters: your customers

Everything above is one token, one grant — everyone who holds it sees every row.
Right for pointing an AI at your own database. Useless the moment you have
users.

The multi-tenant shape is the same config with the token doing more work. Your
backend already knows who's logged in, so it mints a per-user token carrying a
tenant_id:

TOKEN=$(curl -sX POST $BASE/auth/exchange \
  -H "x-exchange-secret: $EXCHANGE_SECRET" \
  -H 'content-type: application/json' \
  -d '{"tenant_id":"11111111-1111-1111-1111-111111111111",
       "subject":"user-123","name":"laptop"}' \
  | jq -r '.data.Result.data.token')

Then every query scopes to the claim in that token instead of a hardcoded id:

      - name: ListTasks
        database: main
        query: |
          SELECT id, title, status, created_at
          FROM mcp_tasks
          WHERE tenant_id = $1::uuid
            AND ($2::text IS NULL OR status = $2::text)
          ORDER BY created_at DESC
          LIMIT 200;
        params:
          - a|ValidateJwt::tenant_id|
          - a|body::status->default(null)|

A row from another tenant doesn't match. Cross-tenant access is structurally
impossible rather than merely forbidden — there's no code path where forgetting
a WHERE clause leaks a customer's data, because the filter is the query.
One endpoint, every customer, each seeing only their own rows.

Revocation, which stateless JWTs can't do alone

A signature check can't tell a revoked token from a valid one — that's what the
mcp_tokens table is for. Every tool re-checks the token's jti against it:

      - name: CheckTokenActive
        run_when_succeeded:
          actions: [ValidateJwt]
          http_code_on_error: 401
        database: main
        hide_data_on_success: true
        query: |
          SELECT (
            $1::uuid IS NULL OR EXISTS (
              SELECT 1 FROM mcp_tokens
              WHERE jti = $1::uuid AND revoked_at IS NULL AND expires_at > NOW()
            )
          ) AS ok;
        params:
          - a|ValidateJwt::jti->default(null)|
        assert:
          http_code_on_error: 401
          error_message: "Token revoked or expired"
          tests:
            - value: "[0]ok"
              is_equal_to: true

Revoking is a call, not an SSH session:

curl -sX POST $BASE/auth/revoke \
  -H "x-exchange-secret: $EXCHANGE_SECRET" \
  -H 'content-type: application/json' \
  -d '{"jti":"<the jti returned at mint time>"}'

The next call is refused: 401 Token revoked or expired on the HTTP route, and
an error result from the tool over MCP. This is the piece a naive JWT setup
forgets.

Already using Auth0, Clerk or Cognito?

Skip the exchange hop entirely. Point is_valid_jwt at your provider's JWKS and
verify their RS256 tokens directly:

            - value: airpipe-jwt
              is_not_null: true
              is_valid_jwt:
                jwks_url: a|ap_var::OIDC_JWKS_URL|
                alg: RS256
                iss: a|ap_var::OIDC_ISSUER|
                aud: a|ap_var::OIDC_AUDIENCE|

Air Pipe fetches and caches the keys, selects the signer by the token's kid,
and enforces iss / aud / exp. Provider key rotation just works. Add a
tenant_id claim in your IdP and the scoping above is unchanged. Needs engine
≥ 0.196.0.

The shortcut

Everything on this page ships as one pack, both tiers, tested end to end — the
schema, the seed endpoint, the single-token tools, the tenant-scoped tools, the
discovery gate, the token lifecycle routes, and the OIDC variant. Fork it, set
two variables, deploy.

If you only want steps 1 through 8 — one token, your own database, no tenancy —
take MCP Quickstart instead. It's the same idea stripped to two tools over
one table, with discovery already gated. Start there and move up when you have
customers; the config shape doesn't change.

You can absolutely hand-roll all of this with the TypeScript SDK instead. You'll
also be hand-rolling the auth, the tenant scoping, the discovery gate, the
revocation denylist, the traces, and a parallel REST API for the clients that
don't speak MCP. That's the trade.

Known limits, so you're not surprised

Tokens are long-lived bearers. MCP clients today authenticate with a static bearer pasted into config — there's no interactive OAuth flow yet. Keep exp short and rely on the denylist for revocation.
One statement per action on Postgres — the driver prepares the query, and a prepared statement holds one command. Use multi: true for a multi-statement DDL block (engine ≥ 0.196.0).
HTTP responses are wrapped in a {"data":{"<Action>":{"data": …}}} action trace, which is why the curl examples pipe through jq. MCP clients parse the tool result for you.

Is tools/list open on your MCP server right now? Worth checking.

Skip the setup

MCP Postgres Starter

Turn your Postgres data into secure MCP tools any AI client (Claude Desktop, Claude Code, Cursor) can call.

Related packs

MCP Quickstart

The smallest useful MCP server: two tools over one Postgres table, guarded by a single shared token, in one config file. Point Claude Desktop, Claude Code, Cursor or any MCP client at your database with no SDK, no Node project and nothing to host. An Air Pipe interface is an HTTP route; add an mcp block and the same interface is also an MCP tool, secured by the same in-config token check. Tool discovery (tools/list) is gated by that same token via list_authorizer, so an unauthenticated client cannot even enumerate your tools or their input schemas. Includes a seed endpoint that creates the table and sample data in one curl.

Latency based container scaling with Orbit

Kav Pather — Mon, 17 Feb 2025 15:01:53 +0000

Haven't read Part 1? Start with Building Orbit: A Lightweight Container Orchestrator in Rust to learn about our journey's beginning.

In our previous article, we introduced Orbit, our lightweight container orchestrator built in Rust. Since then, we've made significant improvements driven by both community feedback and production requirements. Let's dive into the technical evolution that's making Orbit even more powerful and efficient.

Community-Driven Development

One of the most exciting aspects of Orbit's development has been the community engagement. A perfect example is our implementation of CoDel (Controlled Delay) for scaling decisions, which came directly from a community member's suggestion on Medium. We're also grateful to community members like Josselin Chevalay who contributed the pull_policy feature in our latest release, allowing control over container image pulling behavior. This collaborative approach will continue to help shape Orbit's feature set and technical direction.

Technical Evolution: Key Improvements

1. CoDel (Controlled Delay) - Inspired Scaling: Latency-Driven Container Orchestration

Unlike traditional orchestrators that rely solely on CPU and memory metrics, we've implemented CoDel-based/inspired scaling - a feature not natively available in Kubernetes or other major orchestrators. Here's how it works:

pub struct CoDelMetrics {
    service_name: String,
    sojourn_times: VecDeque<(Instant, Duration)>,
    first_above_time: Option<Instant>,
    last_scale_time: Instant,
    config: CoDelConfig,
}

name: adaptive-scaling
instance_count:
  min: 2
  max: 10

# CoDel-inspired adaptive scaling based on request latency
codel:
  target: 100ms                   # Target latency threshold
  interval: 1s                    # Interval for checking delays
  consecutive_intervals: 3        # Number of intervals above target before scaling
  max_scale_step: 1              # Maximum instances to scale up at once
  scale_cooldown: 30s            # Minimum time between scaling actions
  overload_status_code: 503      # Return 503 when overloaded

# Fine-tune scaling behavior
scaling_policy:
  cooldown_duration: 60s         # Wait time between scaling actions
  scale_down_threshold_percentage: 50.0  # Scale down if usage below 50%

spec:
  containers:
    - name: main
      image: airpipeio/infoapp:latest
      ports:
        - port: 80
          node_port: 4335

The CoDel inspired implementation monitors request latency and makes intelligent scaling decisions based on both immediate and historical performance data. Benefits include:

More responsive scaling based on actual service performance
Better handling of latency spikes
Prevention of unnecessary scale-ups during temporary load increases

Note that this is just our initial implementation, and we will continue to improve where possible and perhaps rename when appropriate.

Key Differences from Traditional CoDel:

Service-Level Application :
- Our implementation applies CoDel principles at the service level rather than packet level
- Uses request latency instead of packet sojourn time
- Focuses on scaling rather than packet dropping
State Management :
- This is simpler than traditional CoDel's state machine.

pub struct CoDelMetrics {
    sojourn_times: VecDeque<(Instant, Duration)>,
    first_above_time: Option<Instant>,
    last_scale_time: Instant,
}

2. Health Monitoring

We've added the usual health monitoring with TCP health checks:

pub struct HealthCheckConfig {
    pub startup_timeout: Duration,
    pub startup_failure_threshold: u32,
    pub liveness_period: Duration,
    pub liveness_failure_threshold: u32,
    pub tcp_check: Option<TcpHealthCheck>,
}

This system provides:

Configurable health check parameters
TCP-level connectivity verification
Granular control over failure thresholds
Separate startup and liveness checks

3. Performance Optimizations

We've made several low-level optimizations to improve performance:

Switching to FxHashMap/FxHashSet

use rustc_hash::{FxHashMap, FxHashSet};

pub static INSTANCE_STORE: OnceLock<
    Arc<RwLock<FxHashMap<String, FxHashMap<Uuid, InstanceMetadata>>>>
> = OnceLock::new();

By replacing standard HashMap with FxHashMap:

Reduced memory overhead
Faster hash computation
Better performance for string keys
Lower collision rates in our specific use cases

4. Improved Resource Management

We've implemented a more sophisticated resource management system:

pub struct ResourceThresholds {
    pub cpu_percentage: Option<u8>,
    pub cpu_percentage_relative: Option<u8>,
    pub memory_percentage: Option<u8>,
    pub metrics_strategy: PodMetricsStrategy,
}

This allows for:

Fine-grained control over resource utilization
Better handling of CPU quota management
More accurate memory tracking
Customizable metrics aggregation strategies

Real-World Impact

These improvements have had significant real-world impact:

30% reduction in unnecessary scaling operations
More stable performance under varying load conditions
Reduced resource usage in the orchestrator itself
Better handling of microservices with varying performance characteristics
Still managed to retain a <5MB binary size footprint

What's Next: Decentralized Clustering!?

We're excited to explore our next major development focus: a decentralized clustering solution. This will allow Orbit to:

Operate without a central control plane
Provide better resilience in edge deployments
Enable peer-to-peer node coordination
Support dynamic cluster topology changes

We have some initial ideas on how to design the solution, so please follow for our next update to see how we hope to make this happen!

Building at Scale with Air Pipe

While Orbit handles container orchestration, it's just one piece of the puzzle. At Air Pipe, we're building a comprehensive platform for creating scalable, resilient APIs, integrations, and workflows. Our platform enables you to:

Build and deploy scalable APIs with minimal boilerplate
Create robust integration workflows
Implement resilient data processing pipelines
Leverage edge computing capabilities

If you're building distributed systems or scalable applications, visit airpipe.io to learn how our platform can accelerate your development.

Get Involved

We're building Orbit in the open and value community input. Whether you're interested in the technical details or want to contribute to our upcoming clustering features:

Star us on GitHub
Join our Discord community
Visit Air Pipe
Follow our progress as we build the decentralized clustering solution

Stay tuned for our next technical deep-dive where we'll explore the architecture of our decentralized clustering approach!

Building Orbit: A Lightweight Container Orchestration Tool in Rust

Kav Pather — Thu, 30 Jan 2025 14:43:20 +0000

At Air Pipe, we faced a common challenge in the world of container orchestration - finding the right balance between functionality and complexity. While Kubernetes offers a powerful but complex solution, and Docker Swarm lacks crucial features like autoscaling, we needed something that fit perfectly in the middle. We decided to build Orbit, a lightweight container orchestration tool written in Rust that we're actively developing and improving.

Why We Started

Our journey began with a specific need at Air Pipe. Running a shared-nothing architecture at the edge, we needed a simple way to scale HTTP/TCP based containers without the overhead of complex infrastructure or additional dependencies. We wanted something that could be deployed as a single binary, yet provide robust container management capabilities.

The existing solutions didn't quite fit:

Kubernetes: Too complex for our edge use case, with a large learning curve and resource footprint
Docker Swarm: Too basic, lacking crucial features like autoscaling
Other solutions: Either too complex or too tightly coupled with specific cloud providers or vendors

Starting Simple: Basic Container Management

We started with the basics - a simple Rust application that could manage individual containers. The choice of Rust was deliberate:

Memory safety without garbage collection
High performance and low resource usage
Strong type system and excellent concurrency model
Growing ecosystem of libraries and tools

Our first version could do basic container operations:

async fn start_containers(
    &self,
    service_name: &str,
    containers: &Vec<Container>,
) -> Result<Vec<(String, String)>> {
    // Basic container startup logic
}

Evolution to Pod-Based Architecture

As we developed the system, we realized that managing groups of containers together (pods) would provide better isolation and resource management. This led to a more sophisticated container management system:

pub struct InstanceMetadata {
    pub uuid: Uuid,
    pub created_at: SystemTime,
    pub network: String,
    pub containers: Vec<ContainerMetadata>,
    pub image_hash: HashMap<String, String>,
}

This structure allowed us to track related containers and their metadata together, making operations like scaling and updates more coherent.

The Game Changer: Integrating Pingora

One of our most significant technical decisions was choosing Cloudflare's Pingora framework for our proxy layer. This wasn't just about load balancing - it was about building a robust, high-performance proxy system that could handle production workloads efficiently.

Why Pingora?

Written in Rust, aligning with our technology stack
Battle-tested at Cloudflare's scale
Excellent performance characteristics
Built-in health checking and automatic failover

The integration looked something like this:

name: web-service
instance_count:
  min: 2
  max: 5
spec:
  containers:
    - name: web
      image: airpipeio/infoapp:latest
      ports:
        - port: 80
          node_port: 30080  # This enables Pingora proxy

Adding Intelligence: Resource-Based Autoscaling

One of our proudest features is the intelligent autoscaling system. Instead of just scaling based on simple metrics, we implemented a sophisticated resource monitoring and scaling system:

resource_thresholds:
  cpu_percentage: 80         # CPU usage threshold
  cpu_percentage_relative: 90 # CPU usage relative to limit
  memory_percentage: 85      # Memory usage threshold
  metrics_strategy: max      # Strategy for pod metrics

The system continuously monitors these metrics and makes scaling decisions based on configurable thresholds. Here's a practical example:

name: demo-service
instance_count:
  min: 2
  max: 5
memory_limit: "1Gi"
cpu_limit: "1.0"
resource_thresholds:
  cpu_percentage: 80
  memory_percentage: 85
spec:
  containers:
    - name: infoapp
      image: airpipeio/infoapp:latest
      ports:
        - port: 80
          node_port: 30080
      memory_limit: "512Mi"
      cpu_limit: "0.5"

In this configuration, if CPU usage exceeds 80% or memory usage exceeds 85% across instances, Orbit automatically scales up the service (up to the max instance count). When resource usage decreases, it scales down gracefully while maintaining the minimum instance count.

Where We Are Today

Today, Orbit stands as a testament to what's possible when you focus on solving a specific problem well. It's a single binary under 5MB that provides:

Automated container scaling
Service discovery
High-performance proxying
Volume management
Rolling updates
Prometheus metrics integration

Try It Yourself

Want to see Orbit in action? Here's a simple example to get started:

Download Orbit from our releases
Create a configuration file (e.g., web-service.yml):

name: web-service
instance_count:
  min: 2
  max: 5
resource_thresholds:
  cpu_percentage: 80
  memory_percentage: 85
spec:
  containers:
    - name: web
      image: airpipeio/infoapp:latest
      ports:
        - port: 80
          node_port: 30080

Start Orbit: orbit -c /path/to/configs

Visit http://localhost:30080 to see your service in action, and watch Orbit automatically manage scaling based on resource usage.

Looking Forward

We're continuing to evolve Orbit based on real-world usage and community feedback. Our focus remains on maintaining simplicity while adding powerful features that make container orchestration easier and more efficient.

Want to learn more or contribute? Check out our GitHub repository or join our Discord community.

About Air Pipe

Orbit is just one piece of the puzzle in our mission to simplify and improve the software development lifecycle. At Air Pipe, we're building tools and platforms that make it easier to build, test, and deploy applications. Our shared-nothing architecture and edge computing approach allows for highly efficient and scalable deployments.

Want to learn more about how Air Pipe can help streamline your development workflow? Visit airpipe.io to discover our complete suite of development tools and solutions. See how our platform can help you build better software, faster.

💡 Visit Air Pipe

💡 Find us on Discord

Build Your Own AI API With Google Gemini and Air Pipe

Kav Pather — Sun, 29 Sep 2024 18:11:06 +0000

Artificial Intelligence is at the forefront of innovation, and with Google Gemini AI, developers can unlock advanced capabilities for their applications. However, creating a custom API to tap into Geminis full power can seem complex without the right tools.

Thats where Air Pipe comes in. Air Pipe is a fast, scalable, and secure API platform that simplifies the process of building, deploying, and managing APIs. In this guide, well show you how to leverage Google Gemini AIs API and Air Pipe to create your own AI-powered API in just a few easy steps.

Whether you're looking to automate tasks, enhance your app with AI, or streamline data processing, this tutorial will walk you through generating a Google Gemini API key and configuring a simple yet powerful API using Air Pipe. By the end, you'll have a fully functioning API ready to deployallowing you to integrate cutting-edge AI with ease.

Lets dive in and build something amazing with Google Gemini and Air Pipe!

Step-by-Step Guide to Build Your Own AI API

This tutorial will focus on the cloud platform deployment but will also work seamlessly for self hosted deployments, you can learn how to self host here https://docs.airpipe.io/docs/tutorial/setup .

Prerequisites:

Sign up or log in to Air Pipe.
Google account and API Key

Step 0: Get your Google Gemini API Key

Navigate to https://aistudio.google.com/app/apikey and select Create API Key.

Create a new project if you have not already.

For production deployments we understand your API keys are sensitive, we provide encrypted variable (secret) support https://docs.airpipe.io/docs/configuration/managed-variables .

The examples below will utilize this system storing the key as gemini-key which is then accessed with a|ap_var::gemini-key| .

Other secret stores are also supported.

Step 1: Create your Configuration

Once signed in to your Air Pipe account, head to Configurations > Add New.

Step 2: Create a HTTP POST interface

In the YAML editor paste the below example. Here we simply define a HTTP POST interface and route called gemini/query. We further define our first action to check the body of the payload for a text attribute to exist and assert that it must be less than 20 characters (this is a simple example for illustrative purposes).

Assertions are important to understand as we can control what the user is allowed to input, and then we can further control the outcome of the API and action with the configured tests .

name: AskGemini

interfaces:
  gemini/query: # http route will be defaulted to this interface name
    method: POST
    input: a|body
    output: http

    actions:
      - name: CheckBody
        input: a|body # access the post body as the input to assert
        assert:
          tests:
            - value: text
              is_not_null: true
              is_less_than: 20 # limit the amount of characters

Step 3: Retrieving the full Gemini Response

Lets extend the configuration and pass the text attribute to the Google Gemini API, we do this using a|CheckBody::text| in our configuration. We will also use workflow control, to ensure the CheckBody action succeeds before querying Google Gemini AI with run_when_succeeded.

We are using Action Variables to dynamically substitute the value into the payload, see our docs on variable substitutions for further details and options.

💡 Important! In the URL field below we are using a|ap_var::gemini-key| this implies we have a variable stored on the Air Pipe platform named gemini-key to access. See Managed Variables if youd like to do the same. Otherwise update this with your key or use your own secret store or environment variable if self hosting.

name: AskGemini

interfaces:
  gemini/query:
    method: POST
    input: a|body
    output: http

    actions:
      - name: CheckBody
        input: a|body
        assert:
          tests:
            - value: text
              is_not_null: true
              is_less_than: 20 # limit the amount of characters

      - name: QueryGemini
        run_when_succeeded: [previous] # only run after CheckBody succeeds
        http: 
          url: https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash-latest:generateContent?key=a|ap_var::gemini-key|
          method: POST
          headers:
            content-type: application/json
          body: | # substitute the 'text' we just validated in 'CheckBody' into the body payload
            {"contents":[{"parts":[{"text":"a|CheckBody::text|"}]}]}

Step 4: Deploy and Test

Set your permission as USER_WITH_PUBLIC_READ
Select Deploy to Staging and Deploy to Production and hit create.

Use your favorite API testing tool, or do a curl to your endpoints, lets try the gemini/query route, make sure you update your organization uuid in the route.

You can find your organization uuid under Configurations or in your Organization Settings.

Send a HTTP POST with a JSON payload eg. {"text": "tell me about dogs"} to gemini/query to retrieve the response.
Send a HTTP POST with a JSON payload eg. {"text": "tell me about really big dogs"} to test the length condition triggering a failure and preventing the QueryGemini action from proceeded.

https://api.airpipe.io/YOUR-ORGANIZATION-UUID/production/gemini/query

curl --location 'https://api.airpipe.io/YOUR-ORGANIZATION-UUID/production/gemini/query' \
--header 'Content-Type: application/json' \
--data '{
    "text": "tell me about dogs"
}'

Example response:

{
    "data": {
        "CheckBody": {
            "time.ms": 0,
            "data": {
                "text": "tell me about dogs"
            },
            "message": "success"
        },
        "QueryGemini": {
            "time.ms": 4180,
            "data": {
                "status": 200,
                "headers": {
                    "content-type": "application/json; charset=UTF-8",
                    "vary": "Origin,Accept-Encoding",
                    "date": "Sun, 29 Sep 2024 15:40:42 GMT",
                    "server": "scaffolding on HTTPServer2",
                    "cache-control": "private",
                    "x-xss-protection": "0",
                    "x-frame-options": "SAMEORIGIN",
                    "x-content-type-options": "nosniff",
                    "server-timing": "gfet4t7; dur=4016",
                    "alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000",
                    "accept-ranges": "none"
                },
                "body": {
                    "candidates": [
                        {
                            "content": {
                                "parts": [
                                    {
                                        "text": "## Dogs: Man's Best Friend, and More!\n\nDogs, those furry, wagging companions, have been by our side for thousands of years. They're more than just pets; they're loyal friends, helpful assistants, and sometimes even family members. Let's delve into what makes dogs so special:\n\n**Origins and History:**\n\n* **Wolf Ancestry:** Domestic dogs are descended from wolves, with the earliest evidence of domestication dating back 15,000 years.\n* **Evolution:** Over time, dogs evolved to work alongside humans in various roles like hunting, herding, and guarding. This led to the development of different breeds, each with unique physical and behavioral characteristics.\n\n**Breed Diversity:**\n\n* **Over 300 Breeds:** The world boasts a fascinating variety of dog breeds, each with a distinct appearance, temperament, and purpose.\n* **Classifications:** Breeds are categorized based on their size, coat type, and intended roles, like working, herding, sporting, and companion dogs. \n* **Unique Traits:** From tiny Chihuahuas to massive Great Danes, each breed has its own personality and quirks.\n\n**Personality and Behavior:**\n\n* **Social Creatures:** Dogs are highly social animals, forming strong bonds with their human families.\n* **Intelligence and Trainability:** Many dogs are incredibly intelligent and capable of learning complex commands and tricks. \n* **Emotionally Expressive:** Dogs communicate their emotions through body language, vocalizations, and facial expressions.\n* **Individual Differences:**  While certain breeds tend to have specific temperament traits, each dog is an individual with their own unique personality.\n\n**Health and Care:**\n\n* **Lifespan:** Depending on the breed, dogs can live anywhere from 10 to 20 years.\n* **Nutrition and Exercise:** Dogs require a balanced diet and regular exercise to stay healthy and happy.\n* **Grooming:** Different breeds have different grooming needs, ranging from occasional brushing to daily baths.\n* **Veterinary Care:** Regular checkups, vaccinations, and preventative measures are crucial for maintaining good health.\n\n**Beyond Companionship:**\n\n* **Working Dogs:** Dogs play vital roles in various professions, including law enforcement, search and rescue, assistance for individuals with disabilities, and therapy work.\n* **Emotional Support:** Dogs provide emotional support, reduce stress, and improve mental well-being.\n* **Family Members:** For many families, dogs become cherished members, offering unconditional love, companionship, and joy.\n\n**Getting a Dog:**\n\n* **Research:** Before getting a dog, consider your lifestyle, living situation, and the breed's temperament and care requirements.\n* **Adopting:** Consider adopting a dog from a shelter or rescue organization, giving a loving home to a dog in need.\n* **Responsible Ownership:** Be prepared to provide a dog with a safe, loving environment, proper care, and training.\n\nDogs enrich our lives in countless ways. They offer companionship, loyalty, and unconditional love, making them truly deserving of their title: \"Man's Best Friend.\" \n"
                                    }
                                ],
                                "role": "model"
                            },
                            "finishReason": "STOP",
                            "index": 0,
                            "safetyRatings": [
                                {
                                    "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
                                    "probability": "NEGLIGIBLE"
                                },
                                {
                                    "category": "HARM_CATEGORY_HATE_SPEECH",
                                    "probability": "NEGLIGIBLE"
                                },
                                {
                                    "category": "HARM_CATEGORY_HARASSMENT",
                                    "probability": "NEGLIGIBLE"
                                },
                                {
                                    "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
                                    "probability": "NEGLIGIBLE"
                                }
                            ]
                        }
                    ],
                    "usageMetadata": {
                        "promptTokenCount": 4,
                        "candidatesTokenCount": 642,
                        "totalTokenCount": 646
                    }
                }
            }
        }
    }
}

Step 5: Clean up the Gemini Response

As you can see with the response returned above, Google Gemini returns a lot of additional data you do not need to expose to your end users. We can use post_transforms with extract_value to target the text attribute to return.

Go to Configurations and find your AskGemini configuration and click update, and paste the below.

View Transforms & Functions for further ways to manipulate your data.

name: AskGemini

interfaces:
  gemini/query:
    method: POST
    input: a|body
    output: http

    actions:
      - name: CheckBody
        input: a|body
        assert:
          tests:
            - value: text
              is_not_null: true
              is_less_than: 20 # limit the amount of characters

      - name: QueryGemini
        run_when_succeeded: [previous] # only run after CheckBody succeeds
        http: 
          url: https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash-latest:generateContent?key=a|ap_var::gemini-key|
          method: POST
          headers:
            content-type: application/json
          body: | # substitute the 'text' we just validated in 'CheckBody' into the body payload
            {"contents":[{"parts":[{"text":"a|CheckBody::text|"}]}]} 
        post_transforms:
          - extract_value: ".body.candidates[0].content.parts[0].text"

Example response:

    {
        "data": {
            "CheckBody": {
                "time.ms": 0,
                "data": {
                    "text": "tell me about dogs"
                },
                "message": "success"
            },
            "QueryGemini": {
                "time.ms": 4111,
                "data": "## Dogs: The Best Friends of Humans\n\nDogs, also known as **Canis lupus familiaris**, are domesticated mammals that have been companions to humans for thousands of years. Their loyalty, intelligence, and playful nature have made them beloved pets worldwide.\n\n**Here's a breakdown of some key aspects of dogs:**\n\n**Physical Characteristics:**\n\n* **Size:** Dogs come in a wide range of sizes, from tiny Chihuahuas to massive Great Danes.\n* **Coat:** Dog coats vary in length, texture, and color. Some have short, smooth coats, while others have long, fluffy fur.\n* **Tail:** Most dogs have tails that wag when they are happy. Tail length and shape can vary depending on the breed.\n* **Ears:** Dog ears come in various shapes and sizes, from floppy to erect.\n* **Snout:** Dogs have a strong sense of smell, which is aided by their long, pointed snouts.\n\n**Behavior:**\n\n* **Intelligence:** Dogs are highly intelligent animals, capable of learning complex commands and tasks.\n* **Socialization:** Dogs are social animals that thrive on interaction with humans and other dogs.\n* **Loyalty:** Dogs are known for their loyalty and devotion to their owners.\n* **Playfulness:** Dogs are playful animals that enjoy games and activities.\n* **Training:** Dogs are highly trainable, and with proper training, they can learn a wide range of behaviors.\n\n**Breeds:**\n\nThere are over 300 recognized dog breeds, each with its own unique physical characteristics and temperament. Some popular breeds include:\n\n* **Golden Retriever:** Friendly, intelligent, and eager to please.\n* **Labrador Retriever:** Loyal, playful, and known for their love of water.\n* **German Shepherd:** Intelligent, loyal, and protective.\n* **Poodle:** Intelligent, hypoallergenic, and known for their curly coats.\n* **French Bulldog:** Affectionate, playful, and known for their bat ears.\n\n**Health:**\n\n* **Lifespan:** The average lifespan of a dog is 10-13 years, but some breeds can live longer.\n* **Diet:** Dogs need a balanced diet that is rich in protein, carbohydrates, and essential nutrients.\n* **Exercise:** Most dogs need regular exercise to stay healthy and happy.\n* **Veterinary care:** Regular veterinary checkups and vaccinations are essential for maintaining a dog's health.\n\n**Benefits of Owning a Dog:**\n\n* **Companionship:** Dogs provide companionship and unconditional love.\n* **Stress relief:** Owning a dog can help reduce stress and anxiety.\n* **Exercise and activity:** Dogs encourage their owners to be more active.\n* **Improved mental health:** Studies have shown that owning a dog can improve mental health.\n* **Protection:** Some breeds are known for their protective instincts.\n\n**Conclusion:**\n\nDogs are wonderful companions that offer many benefits to their owners. Whether you're looking for a loyal friend, a playful companion, or a furry family member, there's a dog breed out there for everyone."
            }
        }
    }

Step 6: Restricting and manipulating the text prompt

As youve seen before we can restrict the input text with certain conditions. However we may also want to restrict what we are requesting from Google Gemini AI, or want it to behave or respond in a particular way.

In our example lets say we want a maximum of 100 characters returned only.

We can simply modify the body we are sending to Google Gemini AI to prefix the text with some additional text eg. Your response to the following question should be less than 100 characters: a|CheckBody::text| .

 {"contents":[{"parts":[{"text":"Your response to the following question should be less than 100 characters: a|CheckBody::text|"}]}]}

Complete example:

name: AskGemini

interfaces:
  gemini/query:
    method: POST
    input: a|body
    output: http

    actions:
      - name: CheckBody
        input: a|body
        assert:
          tests:
            - value: text
              is_not_null: true
              is_less_than: 20 # limit the amount of input characters

      - name: QueryGemini
        run_when_succeeded: [previous] # only run after CheckBody succeeds
        http: # store your gemini key in the hosted variables or substitute a|ap_var::gemini-key| with your key if testing # https://aistudio.google.com/app/apikey
          url: https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash-latest:generateContent?key=a|ap_var::gemini-key|
          method: POST
          headers:
            content-type: application/json
          body: | # substitute the 'text' we just validated in 'CheckBody' into the body payload
            {"contents":[{"parts":[{"text":"Your response to the following question should be less than 100 characters: a|CheckBody::text|"}]}]} 
        post_transforms:
          - extract_value: ".body.candidates[0].content.parts[0].text"

Example response:

    {
        "data": {
            "CheckBody": {
                "time.ms": 0,
                "data": {
                    "text": "tell me about dogs"
                },
                "message": "success"
            },
            "QueryGemini": {
                "time.ms": 1907,
                "data": "Dogs are loyal, furry companions known for their intelligence and love. 🐶 \n"
            }
        }
    }

Now you finally have a nice clean response from Google Gemini AI for your end users to consume. We have securely stored the API key, validated the input text, cleaned the data and effectively sandboxed the output response.

So with that youre done! Whats Next?

Air Pipe provides you a fast, consistent and robust development experience that you can continue extending with confidence across anything you build.

You can further extend your configuration to connect to databases and other endpoints all in the one configuration with workflow controls at your disposal.

See:

Performance and Reliability Built on Rust

One of the core strengths of Air Pipe is that it is built on Rust , known for its memory safety , thread safety , and high performance. Whether you're managing large-scale databases or smaller applications, Rust ensures your APIs run smoothly and securely.

Why Google Gemini?

Google Gemini AI is a powerful platform for advanced natural language processing and machine learning, ideal for building intelligent, scalable applications. Its real-time capabilities and seamless integration make it a top choice for AI-driven services.

Conclusion

integrating Google Gemini AI with Air Pipe allows developers to build powerful, scalable APIs with ease. By combining Gemini's advanced AI capabilities with Air Pipe's speed, security, and simple deployment, you can create intelligent applications that handle complex tasks efficiently.

Whether you're automating workflows or enhancing data analysis, this seamless integration empowers you to innovate faster. Start building your API today and unlock new possibilities with Air Pipe and Google Gemini AI.

Ready to get started? Head over to Air Pipe and build your first Gemini API in minutes.

💡Visit Air Pipe

💡Find us on Discord

💡Google Gemini AI Examples

💡https://ai.google.dev/api/all-methods

Build MongoDB APIs in 30 Seconds with Air Pipe

Kav Pather — Fri, 20 Sep 2024 04:15:33 +0000

Are you tired of spending countless hours configuring your APIs and managing complex workflows for your MongoDB database? What if we told you that you could set up a fully functional API in just 30 seconds? In this article, well show you how Air Pipes cutting-edge platform makes API creation fast, efficient, and hassle-free.

Why Air Pipe?

Air Pipe revolutionizes API development, offering a platform where building, deploying, and managing APIs, integrations and workflows takes mere seconds.

Here's why Air Pipe is a game changer:

Instant Deployment : Get your MongoDB APIs running in 30 seconds flat.
Secure & Scalable : Built on Rust for memory and thread safety, ensuring your APIs are secure, fast, and scalable.
Flexible Integration : Effortlessly integrate with databases like MongoDB and more, connect to HTTP endpoints, and run scripts or commands.
Deploy Anywhere : Use Air Pipe's cloud platform or deploy it self-hosted on any infrastructure.

Step-by-Step Guide to Building MongoDB APIs

This tutorial will focus on the cloud platform deployment but will also work seamlessly for self hosted deployments, you can learn how to self host here https://docs.airpipe.io/docs/tutorial/setup .

Prerequisites:

Sign up or log in to Air Pipe.
MongoDB database or if you dont have a MongoDB instance register for MongoDB Atlas, create a free cluster and load the sample dataset.

Step 1: Create your Configuration

Once signed in to your Air Pipe account, head to Configurations > Add New.

Step 2: Define your MongoDB Data Source

Defining your data source is as simple as naming your database , setting a driver and adding a connection string.

For production deployments we understand your connection string is sensitive, we provide encrypted variable (secret) support https://docs.airpipe.io/docs/configuration/managed-variables .

Other secret stores are also supported.

In the YAML editor paste the below example and update the connection string.



name: mongodb-find-example
description: my mongo api

global:
  databases:
    main: 
      driver: mongodb
      conn_string: |
        mongodb+srv://someUser:somePass@bob-perf.hello.mongodb.net/?retryWrites=true&w=majority&appName=my-test

The global block defines the databases, variables, secrets and templates to be used across API interfaces and its subsequent actions.

Step 3: Creating HTTP interfaces

Its trivial to create a HTTP interface with Air Pipe, below we set a route name as mongodb/find , the method as POST and output to http.



name: mongodb-find-example
description: my mongo api

global:
  databases:
    main: 
      driver: mongodb
      conn_string: |
        mongodb+srv://someUser:somePass@bob-perf.hello.mongodb.net/?retryWrites=true&w=majority&appName=my-test

interfaces:
  mongodb/find: # this will be used as our route name
    method: POST # method set to POST so we can accept input data
    output: http # output set to HTTP

The same concept can be used for creating webhooks and creating an entry point to any of your configurations that access databases, commands, scripts and other HTTP endpoints.

Step 4: Define your Actions

Actions are a set of instructions an interface will run when called.

Select your database to connect to i.e. main
Set the document operation and filter.

Well also add a mongodb/update interface while were at it.



name: mongodb-operations
description: use any mongodb operation

global:
  databases:
    main: 
      driver: mongodb
      conn_string: |
        mongodb+srv://someUser:somePass@bob-perf.hello.mongodb.net/?retryWrites=true&w=majority&appName=Cluster0

interfaces:
  mongodb/find:
    method: POST
    output: http

    actions:
      - name: MongoQuery
        database: main
        document_operation:
          database: sample_analytics 
          collection: customers
          operation: findOne
          filter: '{"name": "a|body::name|"}'

  mongodb/update:
    method: POST
    output: http

    actions:
      - name: MongoQuery
        database: main
        document_operation:
          database: sample_analytics
          collection: customers
          operation: updateOne
          filter: '{"name": "a|body::name|"}'
          update: '{"$set": {"active": a|body::status|}}'

For all available operations and settings view https://docs.airpipe.io/docs/configuration/interfaces/actions/inputs/databases#document_operation

Step 5: Deploy and Test

Set your permission as USER_WITH_PUBLIC_READ
Select Deploy to Staging and Deploy to Production and hit create.

Its that easy your API is live and ready to be consumed in seconds.

Use your favorite API testing tool, or do a curl to your endpoints, lets try the mongodb/find route, make sure you update your organization uuid in the route.

You can find your organization uuid under Configurations or in your Organization Settings.

Send a HTTP POST with a JSON payload eg. {"name": "Elizabeth Ray"} to mongodb/find to find a document with a matching name.
Send a HTTP POST with a JSON payload eg. {"name": "Elizabeth Ray", "status": false} to mongodb/update to find a document with a matching name and update the status value accordingly.

https://api.airpipe.io/YOUR-ORGANIZATION-UUID/production/mongodb/find



curl --location 'https://api.airpipe.io/YOUR-ORGANIZATION-UUID/production/mongodb/find' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Elizabeth Ray",
    "status": true
}'

Example response:



{

    "data": {

        "MongoQuery": {

            "time.ms": 3,

            "data": {

                "_id": {

                    "$oid": "5ca4bbcea2dd94ee58162a68"

                },

                "username": "fmiller",

                "name": "Elizabeth Ray",

                "address": "9286 Bethany Glens\nVasqueztown, CO 22939",

                "birthdate": {

                    "$date": {

                        "$numberLong": "226117231000"

                    }

                },

                "email": "arroyocolton@gmail.com",

                "active": true,

                "accounts": [

                    371138,

                    324287,

                    276528,

                    332179,

                    422649,

                    387979

                ],

                "tier_and_details": {

                    "0df078f33aa74a2e9696e0520c1a828a": {

                        "tier": "Bronze",

                        "id": "0df078f33aa74a2e9696e0520c1a828a",

                        "active": true,

                        "benefits": [

                            "sports tickets"

                        ]

                    },

                    "699456451cc24f028d2aa99d7534c219": {

                        "tier": "Bronze",

                        "benefits": [

                            "24 hour dedicated line",

                            "concierge services"

                        ],

                        "active": true,

                        "id": "699456451cc24f028d2aa99d7534c219"

                    }

                }

            }

        }

    }

}

Youre done! Whats Next?

Air Pipe provides you a fast, consistent and robust development experience that you can continue extending with confidence across anything you build.

You can further add testing, and schema validation for your payloads to suit your requirements or fetch additional data if required.

See:

Performance and Reliability Built on Rust

Why MongoDB?

MongoDB is a popular choice for developers due to its flexibility, scalability, and ease of use. Whether you're building a startup or an enterprise-grade application, MongoDB allows you to store and retrieve your data seamlessly. Coupled with Air Pipe's rapid deployment capabilities, it becomes easier than ever to launch and manage data-driven applications.

Conclusion

Building MongoDB APIs doesn't have to be a daunting task. With Air Pipe, you can achieve in 30 seconds what traditionally takes hours or even days. The combination of performance, security, and flexibility makes Air Pipe an ideal solution for developers and businesses seeking to streamline their workflows and get to market faster.

Ready to get started? Head over to Air Pipe and build your first MongoDB API in just 30 seconds!

💡 Visit Air Pipe

💡 Find us on Discord