Using the REST API
Contents
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