doc/DSRestAPI/FS/EPTF_CLL_DsRestAPI_FD.adoc

---
Author: Tamás Levente Kiss
Version: 39/155 16-CNL 113 512, Rev. A
Date: 2016-12-05

---
= EPTF CLL DsRestAPI, Function Description
:author: Tamás Levente Kiss
:revnumber: 39/155 16-CNL 113 512, Rev. A
:revdate: 2016-12-05
:toc:

== How to Read This Document

This is the Function Description for the DsRestAPI feature of the Ericsson Performance Test Framework (EPTF), Core Library (CLL). EPTF Core Library is developed for the TTCN-3 <<_1, [1]>> Toolset with TITAN <<_2, [2]>>.

== Scope

This document is to specify the content and functionality of the DsRestAPI feature of the EPTF Core Library.

== Recommended Way of Reading

The readers are supposed to get familiar with the concept and functionalities of EPTF Core Library <<_3, [3]>>. They should get familiar with the list of acronyms and the glossary.

= General Description

This document specifies the DsRestAPI feature of the CLL.

The DsRestAPI feature provides the following functionality:

* Data can be obtained from the Data Source through HTTP calls and a TTCN API function.
* General HTTP requests are supported (GET, PUT)
* The HTTP server can be started and stopped

= Communicating with the Data Source

DsRestAPI contains API functions that can be used to obtain data in JSON format from the Data Source of CLL.

The feature contains a HTTP server. The server processes the incoming requests and uses a standalone TTCN API to retrieve the response from the Data Source. The communication with the server is done using either the JavaScript API or the Python API.

The following figure shows the flow of communication.

image:images/uimodeldiagram.png[UIModelDiagram]

For more details about the CLL Data Source, please see <<_5, [5]>>.

== General HTTP Server Functions

The following actions are possible using HTTP calls:

* Issuing Data Source requests
* Loading files
* Saving files
* Listing the contents of a directory
* Creating a directory

== Data Source Specific Calls

JSON requests are sent to the HTTP server to communicate with the Data Source through the APIs.

The request can either be a `getData` or a `setData` request.

=== The `getData` Request

The format of the `getData` request is the following:

[source]
----
{
  "getData": {
    "source"
    "element"
    "ptcname"
    "filter": {
      "dataValue" or
      "request"
    }
    "rangeFilter": {
      "offset"
      "count"
    }
    "params": [
      {
        "paramName"
        "paramValue"
      },
      {
        "paramName"
        "paramValue"
      }
    ]
    "selection"
    "writableInfo"
    "children"
    "timeline": {
      "period"
      "maxpoints"
      "since"
    }
  }
}
----

=== The `setData` Request

A `setData` request can have following members:

[source]
----
{
  "setData": {
    "source"
    "element"
    "ptcname"
    "params"
    "content"
    "tp"
    "indxsInList"
  }
}
----

[[the_members_of_the_JSON_requests]]
=== The Members of the JSON Requests

* `source` - the name of the Data Source client; a mandatory string
* `ptcname` - identifies the Data Source together with source; an optional string
* `element` - the name of the element we want to query; a mandatory string
* `rangeFilter` - an optional object that can be used to query parts of a long list. The _offset_ is the first index in the list and the _count_ is the number of maximum elements we want to be returned.
* `params` - the parameters needed to query the given element; an optional object see <<_5, [5]>> for more details about parameters.
* `paramName` - the name of the parameter; a mandatory string member of every `param` object
* `paramValue` - the value of the parameter; a mandatory string member of every `param` object
* `filter`: an optional object that can either have a `dataValue` member, which is a simple string, or a request member. The request is an object that has a source, element, `ptcname` and params. The `paramValues` however are also filter objects, so it is possible to create more complex filters.
* `children` - requests can be nested into one another; an optional list of requests
* `selection`: if the response to a request is a list only the subrequests of the given elements will be processed; an optional list of integers
* `writableInfo` - check whether the corresponding data element is writable. If it is not writable, the response will contain a negative tp.
* `timeline` - get the collected timeline data
** `period` - the number of seconds between measurements
** `maxpoints` the number of measurements to store
** `since` - get only measurements after the given time
* `content` - in a `setData` request, change the value of the given element to this one; a mandatory string
* `tp` - the type of the value as a mandatory integer member, see in `EPTF_DataSource_ValueType`

1.  filtered element
2.  intType,
3.  floatType,
4.  boolType,
5.  charstringType,
6.  octetstringType,
7.  hexstringType,
8.  bitstringType,
9.  integerlistType,
10. floatlistType,
11. charstringlistType,
12. statusLEDType

A negative `tp` means that the element cannot be set.

* _indxInList_: if the response is a list, change only the elements located in the given indexes in the listthis member must be an integer list and it must be present if the response is a list

NOTE: The first four members (`source`, `ptcname`, `element`, `params`) define the element we want to query.
The `children` and `selection` members can be used to create nested requests.

=== The Response

A response is also a JSON object with a single member: `contentList`. The `contentList` can contain two kinds of objects: `node` and `list`.

The `node` object:

[source]
----
{
  "node": {
    "val": string
    "tp": integer
    "childVals": [ node or list objects ]
  }
}
----

The `list` object:

[source]
----
{
  "list": [ node objects ]
}

----

In summary, the response always has the following form:

[source]
----
{
  "contentList": [node or list objects]
}
----

The actual response for a request is contained in the `val` member of the node objects as a string, and `tp` defines its type. The list of available types can be found in <<the_members_of_the_JSON_requests, The Members of the JSON Requests>>.

The `childVals` list contains the responses for the child requests.

If the response represents a timeline, it will be charstring type, whose value is a JSON string (where the quotation marks are escaped). The JSON contains the following members:

* tp: the type of the data
* x: the list of times measurements were taken
* y: the list of datapoints

= APIs

DsRestAPI provides three RESTful APIs that can communicate with the Data Source.

== JavaScript

The JavaScript API can be used in a web application.

Since the API functions are asynchronous, a callback function is called with the returned response in every case.

The following public functions can be used:

* `getData(aHandler`, `aSource`, `aElement`, `aParams`, `aPtcName`): +
Issues a single `getData` request with the given members. The `aHandler` callback will be called with the response.
* `setData(aHandler` , `aSource`, `aElement`, `aContent`, `aType`, `aParams`, `aPtcName`, `aIndxs`): +
Issues a single `setData` request with the given members and calls `aHandler` with the response.
* `getList(aParam, aHandler)`: +
Issues a list of requests contained in the `aParam` parameter.
* `getHelp(callback, source, element)`: +
Gets the help of the given Data Source and element. If the element is missing, the help of the Data Source client will be returned. If the source is also missing, the help of all Data Source Clients is returned. See <<_5, [5]>> for more details about the help.
* `putFile(url, data, callback)`: +
Saves the data in a file specified by the url.
* `loadFile(url, callback)`: +
Calls the callback function with the contents of the specified file.
* `getDirectory(url, callback)`: +
Calls the callback function with the contents of the given directory. The returned value is an object of the form `\{"contentList": [dir_contents]}`.
* `createDirectory(url, callback)`: +
Creates the given directory and invokes the callback when server responds.
* `importJsFile(file, callback)`: +
Imports the given JavaScript file and calls the callback when finished.

== Python

The Python interface is similar to the JavaScript API but it does not contain the file specific functions and the functions are synchronous so the response is simply returned.

The following public functions are available:

* `getData(aSource`, `aElement`, `aParams`, `aPtcName`): +
Issues a single getData request and returns the response.
* `setData(aSource, aElement, aContent, aType, aParams, aPtcName, aIndxs)`: +
Issues a single setData request and returns the response.
* `getList(aParam)`: +
Issues a list of requests contained in the aParam parameter.
* `getHelp(aSource, aElement)`: +
Gets the help of the given Data Source and element.

NOTE: see the corresponding JavaScript function.

== TTCN

See the description of the API function in <<processing_JSON_requests, Processing JSON requests>>.

= Functional Interface

Apart from this description a cross-linked reference guide for the EPTF Core Library Functions can be reached for on-line reading <<_4, [4]>>. This section describes the public TTCN interface of the DsRestAPI feature.

== Naming Conventions

All functions have the prefix `f_EPTF_DsRestAPI_`.

== Public Functions

=== Initialization of the DsRestAPI Feature

Before using the EPTF DsRestAPI functions, the

`f_EPTF_DsRestAPI_init_CT(pl_selfName)`

function should be called. This initializes the EPTF DsRestAPI feature. The name of the component should be passed as parameter `pl_selfName`.

It does the following:

* initializes the needed CLL features (`Base`, `DataSource`, `DsRestAPI`, `DSServer`, `DsRestAPI` Timeline)
* creates and initializes the required component variables
* registers the clean-up function of DsRestAPI (`f_EPTF_DsRestAPI_cleanup_CT`)

=== Starting the DSServer, the HTTP Server and Creating Symlinks

The

[source]
----
f_EPTF_DsRestAPI_start(
  in charstring pl_hostIPAddress,
  in integer pl_hostPort,
  in charstring pl_HTTPServer_dir := “”,
  in charstring pl_customizableApp_dir := “”,
  in charstring pl_API_dir := “”
)
----

function can be used to start the DSServer and the HTTP server. The latter will use the given IP address and hostPort for communication.

The `pl_HTTPServer_dir` server root directory parameter is optional. If specified, the server will be able to serve resources from it, and if not, the server will still serve the RESTful JSON API.

When calling the function in case the argument `pl_HTTPServer_dir` is present, two symlinks are created if their location is given and is not an empty string.

If specified, the `pl_API_dir` should be the directory where the Javascript API for DsRestAPI can be found. The directory will be symlinked to `pl_HTTPServer_dir/utils/DsRestAPI`.

If specified, the `pl_customizableApp_dir` is a user created directory which may contain GUI elements to be used in a GUI. The directory will be symlinked to `pl_HTTPServer_dir/CustomizableContent/CustomizableApp`. If the symlink is created and the `pl_HTTPServer_dir/CustomizableContent/CustomizableApp/TimelineRequest.json` file exists, it will be appended to the Timeline collector. See <<collecting_timelines, Collecting Timelines>> for more details.

=== Stopping the Server

The `f_EPTF_DsRestAPI_stop()` function will stop the HTTP server and delete the created symlinks.

=== Initialization of DSServer

DSServer is a standalone sub-feature that provides the TTCN API for the Data Source and can be used on its own. The `f_EPTF_DsRestAPI_init_CT` function automatically initializes the DSServer as well.

The `f_EPTF_DsRestAPI_DSServer_init_CT(pl_selfName)` function is used to initialize the DSServer when using it without the DsRestAPI feature. The name of the component should be passed as parameter `pl_selfName`.

It does the following:

* initializes the needed CLL features (`Base`, `DataSource`)
* initializes the needed DsRestAPI sub-features:
** `DsRestAPI_Filter` that handles the filters
** `DsRestAPI_Storage` that caches requests and responses
* creates and initializes the needed component variables
* registers the clean-up function of DsRestAPI (`f_EPTF_DsRestAPI_DSServer_cleanup_CT`)

[[processing_JSON_requests]]
=== Processing JSON requests

The

[source]
----
f_EPTF_DsRestAPI_DSServer_processRequest(
  in EPTF_DsRestAPI_Requests pl_request
) runs on EPTF_DsRestAPI_DSServer_CT return EPTF_DsRestAPI_ContentList
----

function can be used to process a request. The function is synchronous.

The function needs a request set organized in a tree as an input. This request tree is built out of atomic `getData` or `setData` request elements, and their children, which are also `getData` or `setData` request elements.

The child request's parameters could depend on the result of its parent requests.

The API calls will also result in an object, representing the response values, organized also in a tree.

The structure of the result tree matches the structure of the request tree. The elements in the response tree are the resulted values of the `getData` and `setData` elements located on the corresponding places of the request tree.

[source]
----
f_EPTF_DsRestAPI_DSServer_processJSONRequest(
  in octetstring pl_request
) runs on EPTF_DsRestAPI_DSServer_CT return octetstring
----

function can be used to process a JSON encoded request. The request will be decoded and the result of `f_EPTF_DsRestAPI_DSServer_processRequestf_EPTF_DsRestAPI_DSServer_processJSONRequest` returned as a JSON encoded octetstring.

The JSON encoded objects are represented by octetstrings. Such octetstrings can be obtained for example from charstrings by using the char2oct function.

[[collecting_timelines]]
=== Collecting Timelines

The DsRestApi Timeline subfeature can be used to collect a timeline of dataelements. DsRestAPI automatically initializes this component.

The feature can also be used standalone, by calling the `f_EPTF_DsRestAPI_Timeline_init_CT` method.

The method `f_EPTF_DsRestAPI_Timeline_start` has to be called to start the timeline collection.

The component is a DataSource Client. Timeline data and other dataelements can be accessed using the DataSource. See <<_5, [5]>> and <<_7, [7]>> for more details.

Timeline collection of an element is started when it is queried for the first time. Requests can also be appended to the timeline manually using the appropriate dataelements. These requests will be issued when the `f_EPTF_DsRestAPI_Timeline_start` function is called.

= Terminology

*Core Library (CLL):* +
It is that part of the TitanSim software that is totally project independent. (i.e., which is not protocol-, or application-dependent). The Core Library is to be supplied and supported by the TCC organization. Any Core Library development is to be funded centrally by Ericsson.

= Abbreviations

CLL:: Core Library

EPTF:: Ericsson Performance Test Framework

MTC:: Main Test Component

PTC:: Parallel Test Component

TitanSim:: New synonym for the EPTF Framework

TTCN-3:: Testing and Test Control Notation version 3 <<_1, [1]>>

GUI:: Graphical user interface

UI:: User interface

API:: Application programming interface

JSON:: JavaScript Object Notation

REST:: Representational State Transfer

= References

[[_1]]
[1] ETSI ES 201 873-1 v3.2.1 (2007-02) +
The Testing and Test Control Notation version 3. +
http://www.etsi.org/deliver/etsi_es/201800_201899/20187301/03.02.01_60/es_20187301v030201p.pdf[Part 1: Core Language]

[[_2]]
[2] User Guide for the TITAN TTCN-3 Test Executor

[[_3]]
[3] EPTF Core Library for TTCN-3 toolset with TITAN, Function Specification

[[_4]]
[4] EPTF CLL for TTCN-3 toolset with TITAN +
http://ttcn.ericsson.se/TCC_Releases/Libraries/EPTF_Core_Library_CNL113512/doc/apidoc/html/index.html[Reference Guide]

[[_5]]
[5] EPTF CLL DataSource, Function Description

[[_6]]
[6] Improving TitanSim’s internal communication and user interfaces

[[_7]]
[7] http://ttcn.ericsson.se/TitanSim/CLL_APIdoc/
[CLL API Doc]