Skip to Content

Services

Programs of plugins that answer calls.

OperationKindHTTP
services.listcallGET /v1/services
services.callcallPOST /v1/services/{plugin}/{name}/{method}
services.servestreamGET /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[]

Request
{
  "id": 1,
  "op": "services.list"
}
Reply
{
  "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

NameWhereRequiredDescription
pluginpathyesThe plugin the service belongs to.
namepathyesThe service's name within its plugin.
methodpathyesOne of the service's methods.

Input

Any JSON value.

Result

any

Request
{
  "id": 1,
  "op": "services.call",
  "args": {
    "plugin": "ask",
    "name": "desk",
    "method": "ask"
  },
  "data": {
    "columns": 2
  }
}
Reply
{
  "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

NameWhereRequiredDescription
pluginpathyesThe plugin the service belongs to.
namepathyesThe service's name within its plugin.

Frames from the server

FrameKindDescription
callJSONA call to answer. Example: {"body":{},"from":{"level":"agent","uid":1001},"id":7,"method":"start"}

Frames to the server

FrameKindDescription
resultJSONThe answer to a call. Example: {"id":7,"result":{"ok":true}}
errorJSONA call that failed. Example: {"error":{"code":"bad_request","message":"no such thing"},"id":7}
Request
{
  "id": 1,
  "op": "services.serve",
  "args": {
    "plugin": "ask",
    "name": "desk"
  }
}
Reply
{
  "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

FieldTypeDescription
agentboolean
declaredboolean
descriptionstring
methodsMethod[]
namestring
uid (optional)integer | nullWho serves it now.
upboolean

Method

FieldTypeDescription
description (optional)string
namestring

On this page