CRI Format
Overview
A CRI (Kinotic Resource Identifier) is used by Kinotic to route requests to the appropriate service, method, or event stream. It is a URI-like format with parts named for clarity within the Kinotic platform.
Format
scheme://[scope@]resourceName[/path][#version]
Everything in brackets ([]) is optional.
Components
Scheme
Identifies the type of resource being addressed.
| Scheme | Description |
|---|---|
srv | Published services and their methods |
stream | Event streams |
Scope
An optional qualifier that narrows the CRI to a specific context, such as a tenant ID, user ID, or device ID. When present, it appears before the @ symbol.
If a scope needs sub-scopes, use the format scope:sub-scope.
srv://tenant-123@app.acme-org.orders-app.OrderService
stream://device-42@app.acme-org.orders-app.temperature/sensor-1
Zone
The leading portion of the resource name places the resource in a zone, the isolation boundary the gateway validates on every send and subscribe. A zone is one or more dot-separated labels of lowercase letters, digits, and interior dashes.
| Zone | Description |
|---|---|
app.<organizationId>.<applicationId> | One application's services. Only that application (and system participants) can call them; only that application can host them. Applications may nest their own sub-zones, e.g. app.acme-org.orders-app.billing. |
app-api | The platform's data plane for applications, such as entity persistence and named query execution. Hosted in-process by the platform only. |
os-api | The platform services organizations manage the system through, such as member, application, and entity definition management. Hosted in-process by the platform only. |
system | Platform-internal services. Only system participants can call or host them. |
Which zones a connection may address is determined by the authenticated participant:
| Participant | May send to | May host in |
|---|---|---|
| APPLICATION (org, app) | app-api.*, app.<org>.<app>.* | app.<org>.<app>.* |
| ORGANIZATION (org) | os-api.* | — |
| SYSTEM | everything | os-api.*, app-api.*, system.* |
Resource Name
The name of the resource being addressed. For services, this is the zone followed by the fully qualified service name. For streams, this is the zone followed by the event type name.
srv://os-api.com.example.UserService
stream://app.acme-org.orders-app.temperature
Path
An optional path that identifies a specific part of the resource, such as a method name on a service.
srv://os-api.com.example.UserService/findById
stream://app.acme-org.orders-app.temperature/sensor-1
Version
An optional semantic version for the resource. Enables versioned service routing so multiple versions of a service can coexist.
srv://os-api.com.example.UserService/findById#1.0.0
srv://os-api.com.example.UserService#2.0.0
Factory Function
The createCRI function provides several overloads for constructing CRI instances:
import { createCRI } from '@kinotic-ai/core'
// From a raw string
const cri1 = createCRI('srv://os-api.com.example.UserService/findById#1.0.0')
// From scheme and resource name
const cri2 = createCRI('srv', 'os-api.com.example.UserService')
// From scheme, scope, and resource name
const cri3 = createCRI('stream', 'tenant-123', 'app.acme-org.orders-app.orders')
// From all components
const cri4 = createCRI('srv', null, 'os-api.com.example.UserService', 'findById', '1.0.0')
CRI Interface
The CRI interface provides methods to access each component:
const cri = createCRI('srv://tenant-123@app.acme-org.orders-app.OrderService/placeOrder#2.0.0')
cri.scheme() // 'srv'
cri.scope() // 'tenant-123'
cri.hasScope() // true
cri.resourceName() // 'app.acme-org.orders-app.OrderService'
cri.path() // 'placeOrder'
cri.hasPath() // true
cri.version() // '2.0.0'
cri.hasVersion() // true
cri.baseResource() // 'srv://tenant-123@app.acme-org.orders-app.OrderService'
cri.raw() // 'srv://tenant-123@app.acme-org.orders-app.OrderService/placeOrder#2.0.0'
Examples
| CRI | Description |
|---|---|
srv://os-api.org.kinotic.os.api.services.iam.MemberService | A platform service in the os-api zone |
srv://app-api.org.kinotic.persistence.api.services.JsonEntitiesRepository/save | A specific method on a platform service |
srv://app.acme-org.orders-app.OrderService/create#1.0.0 | A versioned method on an application's own service |
srv://app.acme-org.orders-app.billing.InvoiceService | A service in an application-declared sub-zone |
srv://system.org.kinotic.orchestrator.api.workload.WorkloadOrchestrationService | A platform-internal service |
stream://app.acme-org.orders-app.temperature | An application's event stream |
srv://node1@system.kinotic-ai.vm-manager.VmManager | A scoped system service targeting one node |