API Clients

All EVA API servers were designed as a simple and user-friendly way to work from a command line using traditional calling methods of Linux http requests: GET, wget, lynx, curl etc. That is why JSON incoming data is always duplicated with the traditional GET/POST request parameters.

API outgoing data is always in JSON format, which can easily be parsed with the use of jq (usually available in all modern Linux distributions), for example:

curl -s 'http://localhost:8812/uc-api/test?k=APIKEY' | jq .version -r

You may call API functions via HTTP GET or HTTP POST - all functions respond similarly regardless of the request method. You may use www-form as well as JSON for POST.

If you want to integrate EVA API in your Python or PHP application, EVA can offer ready-made client libraries.

API client for Python

API client for Python has already been installed on all EVA servers and is used by the system itself. If you want to use the client module on another system, just create eva/client folder, copy lib/eva/client/apiclient.py file into it and create an empty file __init__.py. Other files in this folder are used by the system for a higher level of access to API, which is not publicly documented.

Example of working with API from Python is located in include/python/ folder of EVA.

API classes for Python

API has two classes:

eva.client.apiclient.APIClient()

and

eva.client.apiclient.APIClientLocal(product, dir_eva=None)

APIClientLocal class may be used on the servers where EVA is installed. When specifying product=’<subsystem code>’ parameter (e.g. product = ‘uc’) API is automatically initialized by loading parameters and keys specifically from configuration files of the controller. If you load the apiclient.py module from lib/eva/client/ folder, it is not necessary to set dir_eva parameter. Otherwise, it should point to EVA root folder.

APIClient class should always be initialized manually.

API requires jsonpickle and requests modules.

API initialization

API is initialized with the use of the following functions:

  • set_key(key) set API key.
  • set_uri(uri) set the root API URI (i.e., http://localhost:8812). You don’t need to specify the full path to API.
  • set_timeout(timeout) set maximum request timeout (seconds), 5 seconds by default.
  • set_product(product) set controller type: uc for Universal Controller, lm for Logic Manager, sfa for SCADA Final Aggregator. The client automatically identifies which API is to be called - either SYS API one or the one of the certain controller - that is why this parameter is required.
  • ssl_verify(v) to verify or not SSL certificate validity while working through https://. Can be True (check) or False (don’t check). The certificate is verified by default.

Example:

from eva.client.apiclient import APIClient
api = APIClient()
api.set_key(APIKEY)
api.set_uri('http://192.168.0.77:8812')
api.set_product('uc')

API function call

API functions are invoked by calling the call function:

APIClient.call(func, params=None, timeout=None)

where:

  • params the dict of the request parameters (if required)
  • timeout - maximum time (in seconds) to wait for the API response (if not set - the default timeout is used or the one set during API client initialization).

Example:

from eva.client.apiclient import APIClientLocal
api = APIClientLocal('uc')
code, result = api.call('state', { 'i': 'unit1' })

The function returns a tuple of two variables:

  • code API call result
  • result the result itself (JSON response converted to Python dict or array).

API result codes

Result codes are stored in module variables (i.e. apiclient.result_ok)

# the call succeeded
result_ok = 0
# the item or resource is not found
result_not_found = 1
# access is denied with the set API key
result_forbidden = 2
# server responded with error http status (e.g. API function crashed)
result_api_error = 3
# unknown error: all errors not listed here fall within this category
result_unknown_error = 4
# API is not initialized - URI is not set
result_not_ready = 5
# Attempt to call undefined API function
result_func_unknown = 6
# server connection failed
result_server_error = 7
# the server request exceeded the time set in timeout
result_server_timeout = 8
# API response cannot be parsed or is invalid
result_bad_data = 9
# API function failed
result_func_failed = 10
# API function is called with invalid params
result_invalid_params = 11
# API function attempted to create resource which already exists and can't
# be recreated until deleted/removed
result_invalid_params = 12
# the resource is busy (in use) and can not be accessed/recreated or
# deleted at this moment
result_busy = 13

In case of error, result is an empty dict or contains field “error” which is filled with error message from server (if available).

JSON RPC API client

As EVA ICS uses standard JSON RPC 2.0 protocol, any 3rd party JSON RPC client may be used. In the example below, we’ll use simple JSON RPC client for Python 3.

Installing

Install Python 3 module:

pip3 install jsonrpcclient

Usage example

Let’s call UC API method state and obtain state of sensors:

from jsonrpcclient import request as rpc

r = rpc('http://localhost:8812/jrpc', 'state', k='YOUR_API_KEY', p='sensor')
for s in r.data.result:
    print(s['oid'])

Note

If using custom API client, you may still put API key to X-Auth-Key request header. This is against JSON RPC standard, so if you want to keep it right, you must have k in params of each request.

API result codes

JSON RPC API responds in standard JSON RPC way with HTTP code 200 (OK). In case JSON RPC request has no id, no body is returned and HTTP response code will be 202 (Accepted).

In case of API method errors, HTTP code is still 200 (OK). Error codes can be found in the response body.