Using the REST API

Description & Purpose

The purpose is to Exposes a REST API for the AtomSpace, the CogServer Scheme shell, and the CogServer control commands.

What is REST? REST stands for Representational State Transfer. (It is sometimes spelled "ReST".) It relies on a stateless, client-server, cacheable communications protocol -- and in virtually all cases, the HTTP protocol is used. REST is an architecture style for designing networked applications (See Stack Overflow)

Implemented in Python using the Flask micro-framework and Flask-RESTful extension.

Also see the REST_API

Hands On Tutorial

Start the Rest API

Files (start_restapi.py, exampleclient.py, start-restapi.scm, etc) found here: https://github.com/opencog/opencog/tree/master//examples/restapi

Install atomspace and cogutil

You probably have these installed - (Note: if you have them in your director structure they should be installed - try find -iname cogutil etc)

Update your python path

To find the directory your opencog is installed in, it may be in cd opencog... you might have these directories here : atomspace cogutil ocpkg opencog

Edit your .bashrc (it's in your home directory, and it's hidden because it has a '.' as the first character in the name of the file - try ls -a ~ )

Hint: replace the below paths with your actual git clone path.

The following example assumes you are installing opencog in your home directory:

    export PYTHONPATH="${PYTHONPATH}:/usr/local/share/opencog/python"
    export PYTHONPATH="${PYTHONPATH}:/home/<USERNAME>/opencog/build/opencog/python"
    export PYTHONPATH="${PYTHONPATH}:/home/<USERNAME>/opencog/build/opencog/cython"

If you didn't install in your home directory the paths might look more like this:

    export PYTHONPATH="${PYTHONPATH}:/usr/local/share/opencog/python"
    export PYTHONPATH="${PYTHONPATH}:/<YOUR INSTALL DIRECTORY>/opencog/opencog/python"
    export PYTHONPATH="${PYTHONPATH}:/<YOUR INSTALL DIRECTORY>/opencog/opencog/cython"

then source your .bashrc (to get it reread):

 source .bashrc

Remember to make sure opencog is actually installed...

Start the restapi

There are two options, use either one.

Python: python start_restapi.py
Scheme (guile): guile -l start-restapi.scm

Test that the REST API works

In a separate terminal run python exampleclient.py for interacting with the atomspace.

Try out the Swagger page to muck about with the REST API

OpenCog REST API comes with built-in user-friendly interactive API documentation powered by Swagger.

How to use it: http://wiki.opencog.org/w/REST_API#Interactive_API_Documentation

The Swagger page for the REST API: http://opencog.github.io/rest-api-documentation/

TODO / Qualms

FIX Issue (2017-01-17) : https://github.com/opencog/opencog/issues/2597

Qualm: Should the tutorial be in python or scheme? The main use case of the REST api is to access the visualizer - is the visualizer api in python or scheme?

from some REST client

Linus argues that REST is not that useful to OpenCog (it’s too costly) - but it's not used for everything, and doesn't seem to be a bottleneck atm

Maintained by Misgana, Dagmawi, Adam

OpenCog