MeshAPI: Getting Started
Three steps: describe your service with a manifest, serve discovery plus your ops, and document it with a generated interactive page. The reference eshapiPython package helps with each; none of it is required, because MeshAPI is a format you can implement in any language.
1. Describe: write a manifest
A manifest is a small dict. Each op names its request fields (with type and description) and its response shape.
MANIFEST = {
"meshapi": "0.1",
"service": {
"name": "rns-geo",
"summary": "Geolocation data over Reticulum",
"description": "Geocoding and routing over an authenticated Link.",
"app": "rnsgeo", "aspect": "query", "path": "q",
"dest": "<your destination hash>",
"encoding": "umsgpack",
"source": "https://github.com/you/yourservice",
},
"ops": [
{"op": "rev", "summary": "Reverse geocode", "auth": "none",
"request": {"lat": {"type": "float!", "desc": "latitude"},
"lon": {"type": "float!", "desc": "longitude"}},
"response": {"label": "str", "lat": "float", "lon": "float"}},
],
}
Field types: float, int, str, bool, arrays like [lat,lon]. Suffix ! means required, ? means optional, <=N means max. A field is a bare type string, or an object {type, desc}.
2. Serve: discovery plus your ops
Answer the reserved discovery op on your request path, then dispatch your own ops. Discovery must work regardless of your envelope version.
import meshapi, umsgpack
def on_request(path, data, request_id, link_id, remote_identity, requested_at):
req = umsgpack.unpackb(data)
if meshapi.is_manifest_request(req): # {"op":"__manifest__"}
return umsgpack.packb(meshapi.manifest_reply(MANIFEST, version=1))
ok, err = meshapi.authorize(op_def, remote_identity_hash, allowlist)
... # run the op, return umsgpack
Register it on your destination:
dest.register_request_handler("q", response_generator=on_request,
allow=RNS.Destination.ALLOW_ALL)
3. Document: the interactive page
An executable NomadNet page renders your manifest and runs "try it" as a real Link request to your service, never a backend shortcut:
from meshapi.render import render
from meshapi import client
manifest = client.fetch_manifest(DEST, APP, ASPECT, PATH) # or a local copy
def runner(op, params):
body = {"v": 1, "op": op}; body.update(meshapi.coerce_params(op_def, params))
return client.call(DEST, APP, ASPECT, PATH, body)
print(render(manifest, fields=submitted, runner=runner))
Auth
Per-op uth ublic(anyone), dentity(client must RNS-identify), llow-list(identified plus approved). Enforce it in your handler; the manifest just advertises it so clients know to identify.