REST API Reference

The Analytica REST API provides access to the complete set of functionality. All Analytica clients (e.g., Excel, Shell) use the REST API.

Introduction

In the Technology section on www.analytica.com a fully functioning example of the REST API use is shown: http://www.analytica.com/technology/rest-interface/.

The basic REST API invocation is of the form

http://<analytica server host>:<analytica server port>/<rest api invocation>

All REST API calls are HTTP GET methods at this time, even though they might cause side effects in the server. As an added benefit, all calls can be directly executed using the browser address bar (and can be bookmarked also).

All REST API calls return the same JSON result document structure (which is self-explanatory). To see an example, invoke a few REST APIs through the browser bar and the return will be a JSON document that contains a variety of fields, including the result as well as context data.

REST API Overview

The REST API is grouped into sections. The description of the REST API is done in function signature style. For example,

set(string locationAndName, string xlExpression)

is a REST API and the invocation string will be

http://<analytica server host>:<analytica server port>/set/<locationAndName>/<xlExpression>

This pattern applies without exception: the first segment is the name of the API, and afterwards all parameters follow in the order shown as separate segments.

CONNECTIVITY
autoconnect(string dataSourceHostName, string dataSourceHostPort, 
            string dataSourceLogin, string dataSourcePassword)
  • Effect: connects automatically to all databases on the dataSourceHost
  • The default password for MongoDB databases without authentication is “—” and “—” (three dashes each)
  • dataSourceHostName: hostname of the server where the MongoDB is located
  • dataSourceHostPort: port number of the server where the MongoDB is located
  • dataSourceLogin: login of the database (if defined)
  • dataSourcePassword: password of the database (if defined)
autodiscover(string dataSourceHostName, string dataSourceHostPort, 
             string dataSourceLogin, string dataSourcePassword)
  • Effect: discovers, but does not connect, to all databases on dataSourceHost
  • The default password for MongoDB databases without authentication is “—” and “—”  (three dashes each)
  • dataSourceHostName: hostname of the server where the MongoDB is located
  • dataSourceHostPort: port number of the server where the MongoDB is located
  • dataSourceLogin: login of the database (if defined)
  • dataSourcePassword: password of the database (if defined)
connect(string dataSourceHostName, string dataSourceHostPort, 
        string dataSourceLogin, string dataSourcePassword, 
        string dataSourceName, string dataSourceType)
  • Effect: connects to a single data source
  • The default password for MongoDB databases without authentication is “—” and “—”  (three dashes each)
  • dataSourceHostName: hostname of the server where the MongoDB is located
  • dataSourceHostPort: port number of the server where the MongoDB is located
  • dataSourceLogin: login of the database (if defined)
  • dataSourcePassword: password of the database (if defined)
  • dataSourceName: name of the database
  • dataSourceType: “MongoDB” in case of MongoDB
connectionstatus();
  • Effect: returns a list of all connected data sources
disconnect(string dataSourceHostName, string dataSourceHostPort,
           string dataSourceName, string dataSourceType)
  • Effect: disconnects from this particular data source
  • dataSourceHostName: hostname of the server where the MongoDB is located
  • dataSourceHostPort: port number of the server where the MongoDB is located
  • dataSourceName: name of the database
  • dataSourceType: “MongoDB” in case of MongoDB
disconnectall()
  • Effect: disconnects from all connected data sources
CALCULATED PROPERTIES
set(string locationAndName, string xlExpression)
  • Effect: creates a new calculated property
  • locationAndName: path to the new calculated property
  • xlExpression: XL Expression defining the computation for the value of the new calculated property
forget(string locationAndName)
  • Effect: deletes an existing calculated property
  • locationAndName: path to the calculated property
update(string locationAndName, string xlExpression)
  • Effect: updates an existing calculated property
  • locationAndName: path to the existing calculated property
  • xlExpression: XL Expression defining the computation for the new value of the existing calculated property
get(string pathToProperty)
  • Effect: gets the values of the property
  • pathToProperty: path to an existing property
list()
  • Effect: Lists all calculated property definitions
describe(string pathToPropery)
  • Effect: returns the list of property data types of the property
  • pathToProperty: path to an existing property
CALCULATED PROPERTY PROCESSING

The following three REST APIs must comply to a specific protocol:

  1. call resetallsetstatements() once
  2. call preparesetstatement() any number of times
  3. call executeallsetstatements() once
  4. DO NOT INTERLEAVE ANY OTHER REST API CALLS

The purpose of this is a batch creation of calculated properties that does not have to care about the order in which the calculated properties are defined.

resetallsetstatements()
  • Effect: removes all calculated properties
preparesetstatement(string locationAndName, string xlExpression)
  • Effect: creates a calculated property definition without creating the calculated property itself
  • locationAndName: path to the new calculated property
  • xlExpression: XL Expression defining the computation for the value of the new calculated property
executeallsetstatements()
  • Effect: creates all calculated properties
VIEWS / REPORTS
runreport(string reportName)
  • Effect: executes a defined report
  • reportName: name of report
XL EXPRESSION
parsexl(string xlExpression)
  • Effect: parses the xlExpression and returns either success or parse errors
  • xlExpression: an XL expression
executexl(string xlExpression)
  • Effect: executes the xlExpression and returns the result values
  • xlExpression: an XL expression
fastaccess(string[] parameters)
  • Effect: retrieves properties through direct access without going through XL expressions for retrieval
  • parameters: this list of parameters can be of different types, discussed in the following:

Type 1 (index-based access)

  • parameters[0]: data source name
  • parameters[1]: collection name
  • parameters[2]: index into previous collection
  • parameters[3]: collection name
  • parameters[4]: index into previous collection
  • etc.

The last parameter can either be an index, or collection name or property name. The collection names must be a valid path into a document starting at the data source.

Type 2 (condition-based)

  • parameters[0]: data source name
  • parameters[1]: collection name
  • parameters[2]: simple condition
  • parameters[3]: collection name
  • parameters[4]: simple condition
  • etc.

The last parameter can either be simple condition, or a collection name, or a property name. The collection names must be a valid path into a document starting at the data source

Type 1 and Type 2 can be mixed in the index and conditions can be used at the same time.

VIRTUAL COLLECTIONS
setvc(string virtalCollectionName, string dataSourceName, 
      string dataSourceCollectionName, string dataSourceQuery)
  • Effect: creates a virtual collection
  • virtualCollectionName: name of new virtual collection
  • dataSourceName: name of data source for which virtual collection is created
  • dataSourceCollectionName: name of collection in data source to which query is applied
  • dataSourceQuery: data source native query that selects documents from dataSourceCollectionName into virtualCollectionName
updatevc(string virtalCollectionName, string dataSourceName, 
         string dataSourceCollectionName, string dataSourceQuery)
  • Effect: updates an existing virtual collection
  • virtualCollectionName: name of existing virtual collection
  • dataSourceName: name of data source for which virtual collection is created
  • dataSourceCollectionName: name of collection in data source to which query is applied
  • dataSourceQuery: data source native query that selects documents from dataSourceCollectionName into virtualCollectionName
forgetvc(string virtalCollectionName, string dataSourceName)
  • Effect: removes an existing virtual collection
  • virtualCollectionName: name of existing virtual collection
  • dataSourceName: name of data source for which virtual collection is created
listvc()
  • Effect: lists all definitions of virtual collections
SAVE AS
saveas(string sourceDataSourceName, string sourceCollectionName, 
       string targetDataSourceName, string targetCollectionName)
  • Effect: saves the document from sourceCollectionName in the sourceDataSourceName to the targetCollectionName in the targetDataSourceName (overwrite)
  • sourceDataSourceName: name of the source data source
  • sourceCollectionName: name of the source collection
  • targetDataSourceName: name of the target data source
  • targetCollectionName: name of the target collection
SIZING
setsamplingsize(string newSamplingSize)
  • Effect: sets the sampling size
  • newSamplingSize: new sampling size to take
setsamplingsizedescribe(string newSamplingSizeDescribe)
  • Effect: sets the sampling size for the describe
  • newSamplingSizeDescribe: new sampling size to take for describe
setsamplingsizetypeanalysis(string newSamplingSizeTypeAnalysis)
  • Effect: sets the sampling size for the type analysis
  • newSamplingSizeTypeAnalysis: new sampling size to take for the type analysis
setresultsetsize(string newResultSetSize)
  • Effect: sets the maximum number of documents in the result set
  • newResultSetSize: new result set size to take
setprocessinglimit(string newProcessingLimit)
  • Effect: sets the maximum number of documents to be processed
  • newProcessingLimit: new limit for the number of documents to be processed
getsizingsettings()
  • Effect: retrieves all settings
EXECUTION SEMANTICS
setresultannotation(string resultAnnotation)
  • Effect: adds a property to the result document indicating if the documents are meta-data or instance data
  • resultAnnotation: true/false
setstricttyping(string strictTyping)
  • Effect: enforces strict typing or not. Strict typing takes the order of properties in documents into account
  • strictTyping: true/false
setenforcetypechecking(string enforceTypeChecking)
  • Effect: enforces a semantic check of XL expressions against the inferred types
  • enforceTypeChecking: true/false
setstrictexecution(string strictExecution)
  • Effect: enforces that all properties that are asked for are present/best effort otherwise
  • strictExecution: true/false
getexecutionsettings()
  • Effect: retrieves all execution settings
CONNECTIVITY TESTING
ping()
  • Effect: the Analytica server is pinged and the result JSON document indicates success or not
echo(string parameter)
  • Effect: the parameter is played back; this does not only ping the Analytica server, but also exercises some functionality