Choosing a different port

Example request

Error handling

The REST API returns HTTP response codes. A successful request returns code 200, while error conditions return 400, 404, or 500, indicating the type of the error. When an error occurs, a detailed message is also returned describing the cause of the error.

Interactive API Documentation

OpenCog REST API comes with built-in user-friendly interactive API documentation powered by Swagger.
In addition to browsing documentation for each endpoint easily, you can also play
with the API directly without any coding by filling parameters using the dynamic AJAX UI.

For POST/PUT endpoints, to make documentation easier to read each parameter is listed as form, however in reality they're part of the JSON body's schema. So currently the "Test It Now" functionality of those endpoints don't work as intended. To fix it then either we should make the endpoints understand form parameters as well as JSON, or fix the Swagger annotations to include proper Model schema. Additionally we can suggest or contribute to Swagger (2.0?) project so that Swagger UI can compose simple JSON documents on the fly, but that's probably out of scope. --Hendy (talk) 23:13, 13 July 2014 (CDT)

TruthValue details

TruthValue parameter, formatted as follows:

TRUTHVALUEDETAILS

strength (required)

count (required)

Note: Other TruthValue types have not been implemented yet in the Cython bindings, which are what the REST API uses to interface with the AtomSpace. To support additional TruthValue types in the REST API, the Cython bindings need to be enhanced.

Source

JSONP & CORS Support

The Flask server sets the CORS headers in the response to allow for cross-origin access from web browser applications. For browsers that do not recognize CORS headers, there is a JSONP option. To use JSONP, pass the name of your JavaScript callback function as a parameter in the request. The parameter name must be callback and the value is any valid JavaScript function name. Example: http://127.0.0.1:5000/api/v1.1/atoms?callback=foo. Note that at present, only GET request types are supported.

Unit Tests

Potential Additions

Potential additions to the REST API include:

Change implementation so that it runs as an ordinary opencog Agent; that way, the agent infrastructure can be used to stop & start the thing.

Change STI & LTI to update with deltas, instead of absolute values. Thus, if some other agent updates an STI or LTI at the same time that some REST user does, the REST user will not clobber the update. At most, it can add or subtract to the current STI/LTI. (Requires modifying the underlying code)

Add a CogServer resource to enable control of CogServer requests (Requires modifying the underlying code)

Support pagination

Support sort parameters such as STI

Support advanced filter parameters, such as combining a type filter parameter with an AttentionalFocus filter parameter (Requires modifying the underlying code)

Support atom search by incoming or outgoing set (Requires modifying the underlying code)