Web interface
From OpenCog
The ocweb module implements a HTTP server that provides both a web GUI for navigating the AtomSpace and a REST API. To run it, simply load the module via the shell:
opencog> loadmodule path/to/libocweb.so
Or place it in the CogServer config file.
MODULES = module1.so, module2.so, path/to/libocweb.so
The default opencog.conf file already loads the ocweb module if it's compiled.
Contents |
REST interface
All commands are accessed under the path prefix "/rest/0.2/" (Gama implemented a different REST interface under 0.1, which is incompatible with the current API - 0.2 will revised to 1.0 once a stable URL tree is confirmed. The plan is to continue to support older APIs if they are widely used). By default the HTTP server runs on all interfaces and on http://localhost:17034 but should be configurable to run on other interfaces and ports (TODO). In the rest of this document we will assume the default localhost URL and port.
Results are JSON objects. Parameters are sent to the API either on the HTTP query string or as a JSON object via a POST method.
The primary use of the REST interface will probably to allow external apps to manipulate the AtomSpace. Any of these methods can return
{"error": "... error details" }
If something odd happens. The exact errors returned isn't currently formally defined, but should allow the caller to determine where things went wrong.
Get information about individual atoms
GET http://localhost:17034/rest/0.2/atom?handle=UUID GET http://localhost:17034/rest/0.2/atom/UUID
Replace "UUID" by the UUID of the atom you are after. This returns a json object that looks like:
{ "handle" : UUID, "type": TYPENAME, "name": NAME, "outgoing": [ UUID1, UUID2 ... ], "incoming": [...], "sti": STI, "lti":LTI, "truthvalue": {"simple|composite|count|indefinite": [truthvalue details]} }
See Web Interface#JSON Atom Format for more detail about representing Atoms in JSON notation.
Create a new atom
POST http://localhost:17034/rest/0.2/atom/
with POST data that looks like:
{ "type": TYPENAME, "name": NAME, "outgoing": [ UUID1, UUID2 ... ], "truthvalue": {"simple|composite|count|indefinite": [truthvalue details]} }
This will return one of:
{ "result": "created", "handle": UUID } { "result": "merged", "handle": UUID }
depending on whether a matching atom already existed within the AtomSpace.
Update an atom
POST request to specific existing handle:
http://localhost:17034/rest/0.2/atom/UUID http://localhost:17034/rest/0.2/atom?handle=UUID
with post data that has a JSON object that is the same format as returned by a GET. With the except with only the fields to be updated included. Note that UUID, outgoing/incoming set, type, name are not changeable once an atom is in the AtomSpace. Therefore, the only fields that can be updated are STI/LTI/truthvalue. Examples follow.
Change STI of handle 1 to 10:
POST to http://localhost:17034/rest/0.2/atom?handle=1
{ "sti" :10 }
Change LTI and Truthvalue of handle 1:
POST to http://localhost:17034/rest/0.2/atom?handle=1
{ "lti" :-10, "truthvalue" : {"simple": {"str":0.5, "count":10 } }
Additionally, there are more utility fields for incremental updates.
{ "sti_add" :10 } { "sti_subtract" :10 } { "sti_merge" :10 } { "lti_add" :10 } { "lti_subtract" :10 } { "lti_merge" :10 } { "tv_merge": {...} }
For adding, subtracting, and taking an average of passed STI/LTI and whatever the current value is. Also for merging instead of replacing a truth value.
If successful in updating the atom, then
{ "result": "success" } { "result": "invalid handle" } // if the handle doesn't exist { "result": "invalid property" } // if the property is malformed/unknown
Query for atoms of type/name
GET http://localhost:17034/rest/0.2/list?type=ConceptNode GET http://localhost:17034/rest/0.2/list/ConceptNode
Replace ConceptNode by whatever atom type you like. This returns a json object like:
{ "complete":false, "skipped":0, "total":57, "result": [ 26, 55, 24, 53, 22 ] }
The values are:
- "complete" - whether this is the complete result set for the query.
- "skipped" - how many earlier handles were skipped over (for iteratively calling further atoms).
- "total" - total potential results available.
- "result" - a list of atom Handles for those that match the query.
Other options for this command that can be added to the query string:
- "refresh=1" will make the page refresh every 5 seconds.
- "name=N" display all atoms with name N.
- "handle=UUID" display the atom referred to by UUID in the list. This can be used multiple times.
- "subtype=1" will show subtypes of whatever type is requested.
- "order=X" order the list by STI (X=sti), LTI (X=lti), TV strength (X=tv.s), or TV confidence (X=tv.c).
- "ascend=1" ... used with order. Reverses the direction of the ordering.
Calling server requests
All requests that can be normally carried out via the OpenCog shell are accessible by POST request at http://localhost:17034/rest/0.2/request/*.
For example, to start an agent one makes a POST request:
$ curl http://localhost:17034/rest/0.2/request/agent-start?params=opencog::BackChainingAgent
{ "result": "Successfully started agents" }
Note that the normal shell requests use a variety of parameter formats. However, traditionally the query string of HTTP requests use field=value pairs. So one needs to use the "params" field to specify the parameters of requests.
For example, the PLN sub-command "infer" can optionally take the number of steps to run. However, this would be represented by a post request as shown:
http://localhost:17034/rest/0.2/request/pln?params=infer%205
The params value contains the %20 character, which translate to a space. In some webbrowsers you may be able to enter the URL with spaces and it'll automatically replace them with %20.
Alternatively, you can also send JSON objects corresponding to the request:
$ curl http://localhost:17034/rest/0.2/request/agent-start \ -d "{ "params": "infer 5" }
{ "result": "..." }
JSON Atom Format
The format for atoms returned by GET queries is
{ "handle" : UUID, "type": TYPENAME, "name": NAME, "outgoing": [ UUID1, UUID2 ... ], "incoming": [...], "sti": STI, "lti":LTI, "truthvalue": {"simple|composite|count|indefinite": [truthvalue details]} }
Truthvalues are represented by:
{"count": {"str":0.5, "count":10, "conf":0.5}} {"indefinite": {"l":0.5, "u":0.7, "conf":0.2}} {"simple": {"str":0.5, "count":10}} {"composite": { "primary": {}, "contextual|hypothetical": [ UUID , {TV} ]}
e.g.
{"composite": { "primary": { "simple": {"str":0.5, "count":10} }, "contextual": [ 2313, {"simple": {"str":0.8, "count":11}} ] }
Web UI
The Web UI provides a human friendly interface to navigate the AtomSpace in web browser. Eventually there will be a home page that direct links to various parts of the UI, but currently there are only table based layouts at URLs that follow these formats:
http://localhost:17034/opencog/atom?handle=UUID http://localhost:17034/opencog/atom/UUID http://localhost:17034/opencog/list http://localhost:17034/opencog/list/ConceptNode http://localhost:17034/opencog/server/request/help
Implementation
Gama implemented such an interface a while ago, but it relied on the Http sockets of the CSockets library and this has since been removed from OpenCog's dependencies.
Instead, this implementation uses the Mongoose embeddable http server.
The code has been included in the OpenCog code base due to it being very light weight. It is distributed under the MIT license.
TODO
- home page for OpenCog, including version of software, compiled stuff, links to other interfaces.
- configuration page - interface to config() object.
- Allow configuration to be specified in opencog config file.
- get-list options for listing by name prefix.
- Pagination of get-list results.
- CSS styling of table to make things look pretty.
- Generate graph with SVG or HTML5 canvas for neighbouring atoms of the currently viewed atom (when using get-atom).
