Services
Programs of plugins that answer calls.
| Operation | Kind | HTTP |
|---|---|---|
services.list | call | GET /v1/services |
services.call | call | POST /v1/services/{plugin}/{name}/{method} |
services.serve | stream | GET /v1/services/{plugin}/{name}/serve |
services.list
The services that can be called, and whether each is up.
Host and agent level. Through rookery serve it needs the role view.
Result
Service[]
{
"id": 1,
"op": "services.list"
}{
"id": 1,
"result": [
{
"agent": true,
"declared": true,
"description": "text",
"methods": [
{
"description": "text",
"name": "status"
}
],
"name": "status",
"uid": 1001,
"up": true
}
]
}services.call
Call a method of the service PLUGIN/NAME: JSON in, JSON out.
Host and agent level. Through rookery serve it needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
plugin | path | yes | The plugin the service belongs to. |
name | path | yes | The service's name within its plugin. |
method | path | yes | One of the service's methods. |
Input
Any JSON value.
Result
any
{
"id": 1,
"op": "services.call",
"args": {
"plugin": "ask",
"name": "desk",
"method": "ask"
},
"data": {
"columns": 2
}
}{
"id": 1,
"result": {
"columns": 2
}
}services.serve
For the program that answers a service's calls. While it is open the service is up.
Host and agent level. A stream, as a subscription on the portal or a WebSocket of its own. It does not resume. Through rookery serve it needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
plugin | path | yes | The plugin the service belongs to. |
name | path | yes | The service's name within its plugin. |
Frames from the server
| Frame | Kind | Description |
|---|---|---|
call | JSON | A call to answer. Example: {"body":{},"from":{"level":"agent","uid":1001},"id":7,"method":"start"} |
Frames to the server
| Frame | Kind | Description |
|---|---|---|
result | JSON | The answer to a call. Example: {"id":7,"result":{"ok":true}} |
error | JSON | A call that failed. Example: {"error":{"code":"bad_request","message":"no such thing"},"id":7} |
{
"id": 1,
"op": "services.serve",
"args": {
"plugin": "ask",
"name": "desk"
}
}{
"id": 1,
"result": {
"open": true
}
}
{
"sub": 1,
"data": {
"body": {},
"from": {
"level": "agent",
"uid": 1001
},
"id": 7,
"method": "start"
}
}End the subscription with {"sub": 1, "end": true}.
Types
The named types used on this page.
Service
| Field | Type | Description |
|---|---|---|
agent | boolean | |
declared | boolean | |
description | string | |
methods | Method[] | |
name | string | |
uid (optional) | integer | null | Who serves it now. |
up | boolean |
Method
| Field | Type | Description |
|---|---|---|
description (optional) | string | |
name | string |