JSON-RPC API

From OpenCog
Jump to: navigation, search

Warning, this page is out of date, see Web Interface for a current RESTful/JSON approach

This page outlines the specifications for a JSON-RPC interface for OpenCog (Launchpad blueprint here).

Introduction

From wikipedia:

JSON-RPC is is a remote procedure call protocol encoded in JSON. It is a very simple protocol (and very similar to XML-RPC), defining only a handful of data types and commands. In contrast to XML-RPC or SOAP, it allows for bidirectional communication between the service and the client, treating each more like peers and allowing peers to call one another or send notifications to one another. It also allows multiple calls to be sent to a peer which may be answered out of order.

Implementation

The server implementation should be able to respond to requests, and encapsulate all the below methods in a way that lets XML-RPC be implemented using the same framework (or possibly even Google's fast Protocol Buffers).

The implementation should also let the server be a send requests to the client too. Why? Because it'd be nice to have JSON clients be able to respond to add/remove signals if they want (obviously they have to connect to those signals first and indicate the callback).

There maybe more projects to investigate, but one C++ implementation of JSON-RPC exists at:

http://jsonrpc-cpp.sourceforge.net/

Methods

There are many methods that could be implemented, but initially, a minimum set to be functionally useful should be concentrated on.

AtomSpace

add_atom

Add an atom. Whether this is intepreted as a link or node depends on the atom arity (0 for a node), name (links have no name), and type (whether the given type inherits from node or link).

Returns the handle/UUID of the atom if successful and UNDEFINED_HANDLE if not.

get_atom

Get an atom's detail by handle.

remove_atom

Remove an atom by handle.

set_tv

Set the TruthValue of an atom by handle.

(Should support SimpleTruthValue, CountTruthValue, IndefiniteTruthValue, etc.)

get_tv

Get the TruthValue of an atom by handle.

get_av

Get the AttentionValue of an atom by handle.

set_av

Set the AttentionValue of an atom by handle.

list_type

Return a list of types that the CogServer currently recognises.

get_by_type

Return a list of handles that are of a given Type..

CogServer

load_module, unload_module

Attempt to load/unload a dynamic module.

(Should also create a list_modules command... which lists the modules that are loaded, and a available_modules command which lists the modules that were compiled... although the latter would probably require some CMake wizardry).

get_commands

Return a list of available commands, these should be based on the Request objects registered with the CogServer (i.e the list will change depending on what modules are loaded), but also should include all of the above AtomSpace commands too.

If a string parameter is given, then only return commands that are prefixed with that string. This will be useful for eventually implementing a shell with command completion.

help

Return usage information for any of the commands, and also for the other JSON_RPC calls (so the AtomSpace ones will have to described manually, the CogServer commands have help info already).

agent control

As per those shown in the shell on start up...

  • agents-list: List running agents
  • agents-start: Start some agents
  • agents-start-loop: Start the agent loop
  • agents-step: Run a single cycle of an agent(s)
  • agents-stop: Stop some agents running
  • agents-stop-loop: Stop the agent loop

scm

Possibly needs to considered separately to the other commands, but this should evaluate a string using the Scheme interpreter and return the result.

data

(should probably actually call this load_xml or something)

Similar to scm, but load raw XML.

shutdown

Shutdown the server.