opencog-dev team mailing list archive

[Gustavo Machado Campagnani Gama <gama@xxxxxxxxxxxxx>]

Hi all,

I've pushed the initial revision of my 'REST interface' branch to
lp:~gama/opencog/rest'. There's a section on the 'src/server/README'
with the details but I'm adding a copy of it at the end of this e-mail
for your convenience.

As usual, reviews/comments/criticisms welcome.

--
Gustavo

---------------------------- 8< --------------------------

REST Interface
--------------

The 'RESTServerSocket' class provides a basic HTTP interface that
implements a 'hackish' REST interface on top of the
CommandRequestProcessor. Having a REST interface allows anyone to use a
WWW client (or even build a custom one using any of the dozes of
libraries) that interfaces with the opencog server. Additionally we
automatically get a handful of features provided by the HTTP
server/protocol: secure communication, authentication and a stateless
protocol just to name a few.

Currently, the interface doesn't format the response data in any special
way; it simply returns the raw text data provided by the
CommandRequestProcessor, thus making it a bit hard to automatically
parse and process the server's response. As the REST interface evolves
(along with the functionalities provided by the cogserver itself), we'll
add better formatting of the output wherever appropriate.

The REST server starts on port 17080 by default. To access the service,
all URI's must be prefixed with '/rest/1.0/'. The commands should come
right after the prefix, and any parameters may be supplied as a query
string (for read-only commands, which should be issued using a GET
request) or as form-encoded data on the request body (for write or
read-write commands, which should be issued using a POST request).

                                                                                  
-- Command line examples --

The simples way to test the REST interface is with a command line WWW
client such as wget or curl:

user@opencog-$ src/server/cogserver &
user@opencog-$ curl http://localhost:17080/rest/1.0/help
Available commands:
    data <xmldata>     -- load OpenCog XML data immediately following
    load <filename>    -- load OpenCog XML from indicated filename
    ls                 -- list entire system contents
    ls <handle>        -- list handle and its incoming set
    ls <type> <name>   -- list node and its incoming set
    dlopen <filename>  -- load a dynamic module (and run it).
    dlclose <filename> -- close a previously loaded dynamic module.
    sql-open <dbname> <username> <auth>
                       -- open connection to SQL storage
    sql-close          -- close connection to SQL storage
    sql-store          -- store all server data to SQL storage
    sql-load           -- load server from SQL storage
    exit               -- end the session.
    shutdown           -- stop the server, and exit

user@opencog-$ curl -d "@test_rest.xml" -H "Content-type: application/xml" http://localhost:17080/rest/1.0/data
xml load 1 successful

user@opencog-$ curl http://localhost:17080/rest/1.0/ls
141: node[90:RED] sti:(0,0) tv:(1.000000,0.500000)
118: node[5:1] sti:(0,0) tv:(1.000000,0.500000)
120: node[5:2] sti:(0,0) tv:(1.000000,0.500000)
122: node[5:3] sti:(0,0) tv:(1.000000,0.500000)
124: node[5:4] sti:(0,0) tv:(1.000000,0.500000)
...
161: link[53 sti:(0,0) tv:(1.000000,0.500000) <[47 CW_position],link[13 sti:(0,0) tv:(1.000000,0.500000) <[89 630057840_3],[5 4]>]>]
195: link[53 sti:(0,0) tv:(1.000000,0.500000) <[47 CW_color],link[13 sti:(0,0) tv:(1.000000,0.500000) <[89 630057840_12],[90 RED]>]>]
163: link[53 sti:(0,0) tv:(1.000000,0.500000) <[47 CW_color],link[13 sti:(0,0) tv:(1.000000,0.500000) <[89 630057840_4],[90 PURPLE]>]

[gama@celeborn]:rest-> curl http://localhost:17080/rest/1.0/ls?type=90&name=BLACK'
116: node[90:BLACK] sti:(0,0) tv:(1.000000,0.500000)
        186: link[13 sti:(0,0) tv:(1.000000,0.500000) <[89 630057840_10],[90 BLACK]>]
        182: link[13 sti:(0,0) tv:(1.000000,0.500000) <[89 630057840_9],[90 BLACK]>]
        158: link[13 sti:(0,0) tv:(1.000000,0.500000) <[89 630057840_3],[90 BLACK]>]
        154: link[13 sti:(0,0) tv:(1.000000,0.500000) <[89 630057840_2],[90 BLACK]>]
        150: link[13 sti:(0,0) tv:(1.000000,0.500000) <[89 630057840_1],[90 BLACK]>]
        146: link[13 sti:(0,0) tv:(1.000000,0.500000) <[89 630057840_0],[90 BLACK]>]



-- REST Shell (in Ruby) --

Another option is to use the interactive REST client available at
'<opencog-basedir>/scripts/opencog.rb'. It is written using the Ruby
language, so you will need the Ruvy VM to use it. To start it, just run
the script:

user@opencog-$ scripts/opencog.rb
opencog>

You'll be presented with an IRB prompt (IRB is the Ruby interactive
shell) in which the variable '@opencog' is already set as the "opencog
REST application" object. You may then invoke the same old commands, but
this time using a Ruby-styled syntax:

opencog> puts @opencog.help.get
Available commands:
    data <xmldata>     -- load OpenCog XML data immediately following
    load <filename>    -- load OpenCog XML from indicated filename
    ls                 -- list entire system contents
    ls <handle>        -- list handle and its incoming set
    ls <type> <name>   -- list node and its incoming set
    dlopen <filename>  -- load a dynamic module (and run it).
    dlclose <filename> -- close a previously loaded dynamic module.
    sql-open <dbname> <username> <auth>
                       -- open connection to SQL storage
    sql-close          -- close connection to SQL storage
    sql-store          -- store all server data to SQL storage
    sql-load           -- load server from SQL storage
    exit               -- end the session.
    shutdown           -- stop the server, and exit

opencog> puts @opencog.load.post({:send_representation => 'path=tests/server/atomSpace.xml'})
xml load 2 successful
opencog> puts @opencog.ls.get
141: node[90:RED] sti:(0,0) tv:(1.000000,0.500000)
118: node[5:1] sti:(0,0) tv:(1.000000,0.500000)
120: node[5:2] sti:(0,0) tv:(1.000000,0.500000)
122: node[5:3] sti:(0,0) tv:(1.000000,0.500000)
124: node[5:4] sti:(0,0) tv:(1.000000,0.500000)
...
161: link[53 sti:(0,0) tv:(1.000000,0.500000) <[47 CW_position],link[13 sti:(0,0) tv:(1.000000,0.500000) <[89 630057840_3],[5 4]>]>]
195: link[53 sti:(0,0) tv:(1.000000,0.500000) <[47 CW_color],link[13 sti:(0,0) tv:(1.000000,0.500000) <[89 630057840_12],[90 RED]>]>]
163: link[53 sti:(0,0) tv:(1.000000,0.500000) <[47 CW_color],link[13 sti:(0,0) tv:(1.000000,0.500000) <[89 630057840_4],[90 PURPLE]>]

opencog> @opencog.shutdown.post
user@opencog-$ scripts/opencog.rb

---------------------------- 8< --------------------------