iRetail PRO hub 1.0.0-m5: network
4 operations
← All documentation · Source: contracts openapi/hub-v1.yaml at 8000474.
The chain's private WireGuard network (spec/NETWORK.md).
Operations
PUT
/v1/stores/{id}/network
The store's own switch for the private network (spec/NETWORK.md); null follows the organization. It reaches the store with its record.
operationId
setStoreNetwork · Permission network.manage
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required
|
path | string (uuid) |
|
IRetail-App
|
header | string |
Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking). |
If-Match
|
header | string |
The version the change is based on. |
Request body required
application/jsonStoreNetwork
Responses
GET
/v1/network
The organization's private network (spec/NETWORK.md).
operationId
getNetwork · Permission network.read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
IRetail-App
|
header | string |
Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking). |
Responses
PUT
/v1/network
Turn the private network on or off, set its subnet (only while off) and the endpoint stores reach the hub at.
operationId
putNetwork · Permission network.manage
Parameters
| Name | In | Type | Description |
|---|---|---|---|
IRetail-App
|
header | string |
Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking). |
If-Match
|
header | string |
The version the change is based on. |
Request body required
application/jsonNetworkPut
Responses
GET
/v1/network/peers
Every registered node as a peer of the hub, with its latest handshake as the replicas recorded it.
operationId
listNetworkPeers · Permission network.read
Parameters
| Name | In | Type | Description |
|---|---|---|---|
IRetail-App
|
header | string |
Which app sends the request, at which version: <app>/<version>, optionally a space and (<platform>), as cashier/1.2.0 (windows-x64) or manager/1.2.0 (web). The register (cashier), the back office and the console (manager) and the device gateway (gateway) send it on every request; a request without it is not one of the apps and is served as the current API, and a device token of an app's kind without it is an app of an unknown version; a header that does not parse counts as absent. The node may refuse an app 426 app_update_required by it, except on the operations marked x-app-update-exempt. Not a security boundary (spec/API.md, Transport; spec/RELEASES.md, Who is asking). |
Responses
Schemas
HubStore object
A store as the hub keeps it, with its node's state (null before a node registers).
Node object
id required
|
string (uuid) |
|
store_id required
|
string (uuid) |
|
status required
|
"active" | "revoked" |
|
version required
|
string |
The node's version at its last exchange. |
connected required
|
boolean |
An exchange is open now. |
last_seen_at required
|
string (date-time) | null |
|
hub_cursor required
|
integer (int64) |
The last hub seq the store applied. |
hub_head required
|
integer (int64) |
The hub's newest seq for this store; hub_head − hub_cursor is how far behind the store is. |
store_ack required
|
integer (int64) |
The last store seq the hub applied. |
store_head required
|
integer (int64) |
The store's newest seq at its last exchange; store_head − store_ack is what waits to arrive. |
certificate_expires_at required
|
string (date-time) |
|
registered_at required
|
string (date-time) |
|
health required
|
NodeHealth | null |
The store's last health report (spec/HEALTH.md), or null before the first. |
compatibility required
|
Compatibility | null |
Why the hub refuses this node at the exchange (spec/RELEASES.md, Compatibility), until it connects; null otherwise. |
NodeHealth object
reported_at required
|
string (date-time) |
|
started_at required
|
string (date-time) |
|
shifts_open required
|
integer |
|
oldest_shift_opened_at required
|
string (date-time) | null |
|
journal_pending required
|
integer (int64) |
|
search_queue required
|
integer (int64) |
|
redis_ok required
|
boolean |
|
tunnel_state required
|
"off" | "up" | "down" | null |
The store's tunnel to the hub (spec/NETWORK.md); null from a node that does not report it. |
audit_head required
|
object | null |
The head of the store's audit chain from its last report (spec/AUDIT.md, Anchors); null from a node that does not report it. |
update required
|
NodeUpdate | null |
The store's update from its last report (spec/RELEASES.md); null from a node that does not report it. |
apps required
|
array of AppVersionCount |
Per app, platform and version, how many of the store's devices run it, failed it and are silent, from its last report (spec/RELEASES.md, Reporting); empty from a node that does not report them. |
app_offers required
|
array of AppOffer |
The store's offers of the release it runs (spec/RELEASES.md, One device first). |
StoreNetwork object
network_enabled required
|
boolean | null |
false keeps the store out of the private network; null follows the organization. |
NetworkPut object
enabled required
|
boolean |
|
subnet required
|
string |
An aligned IPv4 network inside 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 or 100.64.0.0/10, prefix /8 to /22. |
endpoint required
|
string | null |
host:port where stores reach the hub's UDP listener; required to turn the network on. |
Network object
enabled required
|
boolean |
|
subnet required
|
string |
|
endpoint required
|
string | null |
|
hub_address required
|
string |
The hub's address inside the tunnel, the subnet's first host. |
hub_public_key required
|
string | null |
The hub's WireGuard public key (standard base64), or null without a key file. |
key_present required
|
boolean |
The hub found its key file (IRETAIL_WG_KEY). |
version required
|
integer (int64) |
NodeUpdate object
The update fields of a store's last health report (spec/HEALTH.md, spec/RELEASES.md).
running_version required
|
string |
|
previous_version required
|
string | null |
|
target_version required
|
string | null |
|
target_record_version required
|
integer (int64) |
|
state required
|
UpdateState |
|
state_since required
|
string (date-time) | null |
|
step required
|
UpdateStep | null |
|
error required
|
string | null |
|
healthz required
|
"ok" | "failing" | null |
|
backup required
|
UpdateBackup | null |
The pre-update archive of the target's attempt; null before it or from a node that does not report it. |
rehearsal required
|
UpdateRehearsal | null |
|
background_tasks_running required
|
integer |
The store's background tasks pending or running (spec/RELEASES.md, Migrations). |
background_tasks_failed required
|
integer |