Docs
Kiwi Distro
Version Current

How-to guide

Expose a REST API with the SideCar

Turn an existing REST API into Kiwi methods with a mapping document, and call other Kiwi services from a local application.

Distro Current 3 min read Updated

Prerequisites

  • An existing REST API reachable from where the SideCar will run
  • A service and worker profile for the SideCar to register as

Note

Kiwi Distro is currently in private preview. Interfaces and behaviour described here can change before general availability. Contact Kiwify Labs for access.

The SideCar (ksc) is a companion process that registers as a worker, so existing services join the platform with no code changes. It does two jobs:

  1. API proxy. It turns calls to Kiwi methods into calls to an external REST API, using a mapping document.
  2. Local ambassador. It gives a local application a loopback endpoint for calling other Kiwi services.

The mapping document#

One JSON document per service. Fields:

Field Meaning
version Opaque version string. A SideCar re-downloads the document when its local version differs
target_profiles[] profile_name, base_url and shared headers[] for an external API
mappings[] Each maps source (method_name, params[] with param_type, is_required, regex_validation, default_value) to target (target_profile, target_url with {placeholder} taken from source params, http_method, optional param_type of JSON, XML or Form plus params[], headers[])

In param_value and header_value you can interpolate param(name), env(NAME) and secret(name); the last reads a service secret delivered at registration, so credentials stay out of the document.

Upload it#

bash
kiwi distro upload-sidecar-mappings --service-id <service-id> --file Mappings.json
kiwi distro get-sidecar-mappings    --service-id <service-id>              # metadata
kiwi distro get-sidecar-mappings    --service-id <service-id> --document   # the full JSON
kiwi distro delete-sidecar-mappings --service-id <service-id>

The middleware validates the document: it must be valid JSON with a non-empty version and a mappings[] array, and every mapping needs a routable, unique source.method_name (letters, digits and underscore). A bad upload is rejected with 400.

Mapping documents are stored in the middleware's database by default, or in a file store (a path or mounted bucket) through the pluggable sidecar-store module.

Run the SideCar#

Configure it like any worker (worker_id, execution_mode, auth_secret, middleware_url, middleware_ca_url) plus:

Key Default Meaning
sidecar:mappings_file Mappings.json next to the binary Local cache of the document
sidecar:proxy:timeout_seconds 100 Ceiling for each outbound request
sidecar:local_server:enabled true Run the loopback ambassador
sidecar:local_server:port 55080 Ambassador port

On start it authenticates, resolves its service id, fetches the mapping document if its cache is missing or stale, registers one method per mapping, and starts the ambassador. If no document has been uploaded it still starts, with no proxy methods.

Call Kiwi services from a local app#

The ambassador listens on loopback only. Every request must carry X-Sidecar-Token, with the value from the sidecar.local.token file the SideCar writes.

Route Purpose
POST /api/request Body is a method request; returns the method response
POST /api/submit Returns { "request_id": ... }. If a callback URL is given, the response is posted there when done
GET /api/result/{requestId} Fetches a result

Expected result

  • Kiwi clients can call the REST API as service/method