Differences

This shows you the differences between two versions of the page.

--- en:mervis-scada:50-api [2026/07/08 14:18]
z.moustis
+++ en:mervis-scada:50-api [2026/07/17 12:41] (current)
z.moustis
@@ Line 5: / Line 5: @@
 **Important Note on Formatting:** While JSON is heavily utilized in newer endpoints, the only officially supported backward-compatible response format across the entire legacy API is XML.
-===== List of Basic API Methods =====
+===== Supported API Methods =====
-Below is the complete list of available API endpoints and their definitions.
+Below is the consolidated list of recommended API endpoints. Note: Only methods with fully documented and verified examples are listed below.
 ^ Function ^ Description |
-| **Authentication & Session** | |
+| **Authentication** | |
-| ''api/v2/get/authenticate'' | **[Recommended]** Authenticates a user and returns a session token for subsequent API calls. |
+| ''api/v2/get/authenticate'' | Authenticates a user and returns a session token for subsequent API calls. |
-| ''api/checkCredentials'' | **[Deprecated]** Verifies user credentials and returns a token. Use ''v2/get/authenticate'' instead. |
-| ''api/logout'' | Ends the current user session and invalidates the active authentication token. |
 | **Project & Data Structure** | |
 | ''api/get/projects'' | Retrieves a list of all projects accessible to the logged-in user. |
-| ''api/get/projectData'' | Fetches overarching metadata, configuration, and settings for a specific project. |
 | ''api/get/projectByParts'' | Retrieves the visual tree structure and the list of datapoints within a specific project. |
-| **Historical Data** | |
+| **Reading Data** | |
-| ''api/v3/get/history'' | **[Recommended]** Downloads historical trend data for one or multiple series in a single, paginated call. |
-| ''api/get/history'' | **[Deprecated]** Legacy method to retrieve historical trend data. |
-| ''api/get/history/specific'' | Retrieves specific historical datapoints relative to a provided reference time. |
-| ''api/set/history'' | Inserts new historical data values into the database. |
-| ''api/replace/history'' | Completely replaces existing historical data within a specified time range. |
-| **Real-Time Data & Control** | |
 | ''api/get/values'' | Retrieves the current, real-time values of specified datapoints. |
-| ''api/get/changes'' | Polls for state changes or value updates that occurred since the user's last request. |
+| ''api/v3/get/history'' | Downloads historical trend data for one or multiple series in a single, paginated call. |
+| ''api/get/history/specific'' | Retrieves specific historical datapoints relative to a provided reference time. |
+| **Writing & Execution** | |
 | ''api/set/values'' | Writes new values to specified datapoints. |
 | ''api/set/executeActions'' | Executes predefined actions or buttons (e.g., INIT, ZAP commands) on datapoints. |
-| ''api/set/projectPriorityRefresh'' | Triggers an immediate, high-priority data refresh from the hardware controllers to the SCADA server. |
+| ''api/set/history'' | Inserts new historical data values into the database. |
-| **Alarms & Events** | |
+| ''api/replace/history'' | Completely replaces existing historical data within a specified time range. |
-| ''api/get/alarms'' | Retrieves the current active alarms for a project or specific datapoint. |
-| ''api/get/alarmHistory'' | Retrieves the historical log of alarm states, triggers, and acknowledgements. |
+**Note on Credentials:** You can test these API calls using the credentials `n: demo` and `p: demo`. For production applications, it is required to exchange these credentials for a token using `api/v2/get/authenticate` and use the resulting token (`t: [token_string]`) in subsequent calls to ensure optimal performance.
-| ''api/get/eventHistory'' | Retrieves a log of system or user events (e.g., configuration changes, log-ins). |
-| ''api/set/executeAlarmOps'' | Executes operations on alarms, such as acknowledging or clearing them. |
-| **Graphical Schemas (HMI)** | |
-| ''api/get/schema'' | Retrieves the layout definition and structural data for a graphical schema (dashboard). |
-| ''api/get/schema/datapoints'' | Retrieves the specific datapoints mapped to a particular graphical schema. |
-| ''api/get/schema/values'' | Retrieves the current values specifically required to render a graphical schema. |
-| ''api/get/schema/image'' | Retrieves static image assets and background graphics associated with a schema. |
-===== Authentication Examples =====
+===== Authentication =====
 ==== api/v2/get/authenticate ====
@@ Line 62: / Line 48: @@
   * **tokenValidFor** (TimeSpan) - The duration for which the provided token is valid (e.g., "P1D" = 1 day).
   * **changePwdBefore** (DateTime or null) - Specifies the date and time by which the current password must be changed.
-  * **notifyNearingPwdExpirationIn** (TimeSpan or null) - Indicates how long before the password expires a notification should be displayed.
 <code javascript>
@@ Line 74: / Line 59: @@
         "Login": "demo",
         "NotifyNearingPwdExpirationIn": null,
-        "Token": "3:93d3c832-0f1b-4cde-a0eb-1fd346f5a9c0",
+        "Token": "3:b83d56f8-2e25-4745-a4e5-1a259c286c5f",
         "TokenValidFor": "P1D",
         "User": "48141739-5d16-4ca3-8ae1-33e27d9eb22e",
@@ Line 83: / Line 68: @@
 </code>
-==== [Deprecated] api/checkCredentials ====
+===== Reading Data =====
-**Note:** Use ''api/v2/get/authenticate'' instead.
-**Request:**
-  * **URL:** ''/api/checkCredentials?format=xml''
-  * **Method:** POST
-<code javascript>
-{"cred":{"n":"demo","p":"demo"}}
-// or with full name:
-{"cred":{"n":"GlobalDomain\\demo","p":"demo"}}
-</code>
-**Response:**
-<code xml>
-<?xml version="1.0" encoding="utf-8"?>
-<checkCredentialsResult xmlns:r="http://dev.rcware.eu/serialization/references" d="GlobalDomain" l="demo" t="2:85be00d3-5875-4dec-a9b4-c98e2ff2acbe" xmlns="http://dev.rcware.eu/auth" />
-</code>
-* You **should** use the received token **t** in subsequent API calls.
-===== Reading Data Examples =====
 ==== api/get/values ====
-The right way to retrieve current values of data points (property "Output") from one or multiple projects.
+Retrieves current values of data points (property "Output") from one or multiple projects.
 **Request:**
@@ Line 114: / Line 79: @@
 <code javascript>
 {
- "cred": { "t": "xxxxxx" },
+ "cred": {
+  "n": "demo",
+  "p": "demo"
+ },
  "propNamesToSerialize": ["Output"],
  "offset": 0,
@@ Line 120: / Line 88: @@
  "serverState": null,
  "dps": [{
-   "projId": "ba1a92f7-f213-4a72-90e4-f7142b50274b",
+   "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
-   "dpIds": ["e089dde2-a097-4e0d-8012-c8cf3dc62694", "1089dde2-a097-4e0d-8012-c8cf3dc62696"]
+   "dpIds": ["62cf4083-31ed-4bc1-be25-044ba837a9f0"]
   }]
 }
@@ Line 129: / Line 97: @@
 <code xml>
 <?xml version="1.0" encoding="utf-8"?>
-<values xmlns:r="http://dev.rcware.eu/serialization/references" nextOffset="-1" serverTime="2020-04-07T07:46:34.850422Z" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/datapoints">
+<values xmlns:r="http://dev.rcware.eu/serialization/references" nextOffset="-1" serverTime="2026-07-17T10:29:17Z" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/datapoints">
  <vals>
-  <v projId="ba1a92f7-f213-4a72-90e4-f7142b50274b" dataVersion="637217783110000000" serverTime="2020-04-07T07:46:34.850422Z">
+  <v projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" serverTime="2026-07-17T10:29:17Z">
    <dps>
-    <d id="e089dde2-a097-4e0d-8012-c8cf3dc62694" serAlr="true">
+    <d id="62cf4083-31ed-4bc1-be25-044ba837a9f0" serAlr="true">
      <props>
-      <p n="Output" t="2020-04-07T07:43:42.1000676Z" q="Bad" r:type="177e726a-3180-4152-bef2-6254e7055e1f">
+      <p n="Output" t="2026-07-17T10:29:17Z" q="Good" r:type="b133774d-21ce-42b6-add3-57c012079c55">
-       <n1:v>ON</n1:v>
+       <n1:v>13851.42</n1:v>
       </p>
      </props>
@@ Line 150: / Line 118: @@
 **Rules:**
-  * Always use "token" instead of "name" and "password". Non-token calls are slower.
+  * Items "segmentation", "requestState", and "serverState" should always copy the values from the last server response for pagination. The first call should use an empty "segmentation".
-  * "seriesParameters" [optional] - use only if requesting different parameters than "commonSeriesParameters".
-  * "clientReference" [optional] - use for your own identification of the series.
-  * Items "segmentation", "requestState", and "serverState" should always copy the values from the last server response. The first call should use an empty "segmentation".
 **Request:**
@@ Line 161: / Line 126: @@
 <code javascript>
 {
-    "credentials": { "token":"guid" },
+    "credentials": {
+        "name": "demo",
+        "password": "demo"
+    },
     "request": {
         "commonSeriesParameters": {
-            "from": "2018-12-01T00:00:00Z",
+            "from": "2026-06-20T00:00:00Z",
-            "to": "2018-12-01T10:00:00Z"
+            "to": "2026-07-17T00:00:00Z"
         },
         "series": [
             {
-                "clientReference": "myId1a",
+                "clientReference": "test1",
                 "provider": {
                     "parameters": {
@@ Line 193: / Line 161: @@
   * **ts** - timestamp (start of validity period)
   * **gt** - goodthrough (end of validity period)
-  * **i** - interval (only present if it differs from Meta section)
   * **meta.interval** - expected interval between stored records. Useful to identify missing data.
+<code javascript>
+{
+    "result": { "code": 0, "subCode": 0, "message": "" },
+    "data": {
+        "count": 1,
+        "historyData": [
+            {
+                "clientReference": "test1",
+                "provider": {
+                    "id": "689e32fa-24a2-448e-9374-6158e6e6cb15",
+                    "parameters": {
+                        "projectId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
+                        "dataPointId": "62cf4083-31ed-4bc1-be25-044ba837a9f0"
+                    }
+                },
+                "meta": { "type": "double", "unit": "h", "interval": "PT3M" },
+                "values": [
+                    { "v": 13851.4, "ts": "2026-06-25T12:00:00.000Z" }
+                ]
+            }
+        ]
+    },
+    "segmentation": { "requestState": "", "serverState": "" }
+}
+</code>
 ==== api/get/history/specific ====
@@ Line 200: / Line 193: @@
   * **URL:** ''/api/get/history/specific?format=json''
   * **Method:** POST
-  * **dataSpec:** Defines the specific point to fetch:
+  * **dataSpec:** Defines the specific point to fetch (e.g., 2 = First value less than reference time).
-     * 0 = MinTimestamp
+  * **refTime:** Reference time required for specific temporal searches.
-     * 1 = MaxTimestamp
-     * 2 = FirstLessThanReferenceDateTime
-     * 3 = FirstLessThanOrEqualThanReferenceTime
-     * 4 = FirstGreaterThanReferenceDateTime
-     * 5 = FirstGreaterThanOrEqualThanReferenceTime
-     * 6 = MaxGoodThroughTime
-  * **refTime:** Reference time required for dataSpecs 2 through 5.
 <code javascript>
 {
- "cred": { "t": "xxxxxx" },
+ "cred": {
- "projId": "b4d96a6d-2b3d-48eb-af30-d11e875ba7ed",
+  "n": "demo",
+  "p": "demo"
+ },
+ "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
  "offset": 0,
  "count": 1000,
  "dataSpec": 2,
  "refTime": "\/Date(1692788459000)\/",
- "dpIds": ["58426e69-46ba-4925-9a5c-d7d65efb9886"]
+ "dpIds": ["62cf4083-31ed-4bc1-be25-044ba837a9f0"]
 }
 </code>
-==== [Deprecated] api/get/history ====
+===== Writing Data & Execution =====
-**Request:**
-  * **URL:** ''/api/get/history?format=xml''
-  * **Method:** POST
-<code javascript>
-{
-   "cred":{ "n":"demo", "p":"demo" },
-   "projId":"5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
-   "dpId":"62cf4083-31ed-4bc1-be25-044ba837a9f0",
-   "from":"/Date(1541199600000)/",
-   "to":"/Date(1541496190357)/",
-   "offset":0,
-   "count":5000,
-   "historyState":""
-}
-</code>
-**Response:**
-<code xml>
-<?xml version="1.0" encoding="utf-8"?>
-<getHistoryResult xmlns:r="http://dev.rcware.eu/serialization/references" r:type="b133774d-21ce-42b6-add3-57c012079c55" xmlns:n1="http://dev.rcware.eu/scada/basic-props" xmlns="http://dev.rcware.eu/scada/history">
-  <hist projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dpId="62cf4083-31ed-4bc1-be25-044ba837a9f0" propName="Output" interval="PT3M" historyState="" nextValOfs="-1">
-    <errMsg/>
-    <vals>
-      <hv ts="2018-11-02T21:26:08.7936747Z" gt="2018-11-03T20:35:08.8060769Z">
-        <n1:v>12754</n1:v>
-      </hv>
-    </vals>
-  </hist>
-</getHistoryResult>
-</code>
-===== Writing Data Examples =====
 ==== api/set/values ====
@@ Line 265: / Line 221: @@
 <?xml version="1.0" encoding="UTF-8"?>
 <setValuesRequest xmlns:r="http://dev.rcware.eu/serialization/references" xmlns="http://dev.rcware.eu/scada/datapoints" xmlns:n2="http://dev.rcware.eu/auth" xmlns:n1="http://dev.rcware.eu/scada/comm-props" >
-   <n2:cred t="xxxxxx"/>
+   <n2:cred n="demo" p="demo"/>
         <values projId="1b2623be-eaa4-4e29-8596-c66dd85d5643">
             <dps>
@@ Line 288: / Line 244: @@
 <?xml version="1.0" encoding="UTF-8"?>
 <executeActionsRequest xmlns="http://dev.rcware.eu/scada/action-defs" xmlns:n2="http://dev.rcware.eu/scada/basic-props" xmlns:n1="http://dev.rcware.eu/auth" xmlns:r="http://dev.rcware.eu/serialization/references">
-  <n1:cred t="xxxxxx"/>
+  <n1:cred n="demo" p="demo"/>
   <actionDefs projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0">
     <actions>
@@ Line 313: / Line 269: @@
 <?xml version="1.0" encoding="UTF-8"?>
 <replaceHistoryRequest xmlns="http://dev.rcware.eu/scada/history" xmlns:n2="http://dev.rcware.eu/auth" xmlns:n1="http://dev.rcware.eu/scada/basic-props" projId="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" dpId="e86dba6d-1250-4e7f-aafb-84fd28324710" from="2020-03-15T11:00:00+00:00" to="2020-03-18T11:00:00+00:00">
-  <n2:cred t="xxxxx"/>
+  <n2:cred n="demo" p="demo"/>
   <vals>
     <hv ts="2020-03-15T11:00:00+00:00" i="P1D">
@@ Line 325: / Line 281: @@
 </code>
-===== Project Examples =====
+===== Projects Management =====
 ==== api/get/projects ====
@@ Line 334: / Line 290: @@
 <code javascript>
 {
- "cred": { "t": "xxxxxx" },
+ "cred": {
+  "n": "demo",
+  "p": "demo"
+ },
  "offset": 0,
  "count": 250
 }
+</code>
+**Response:**
+<code xml>
+<?xml version="1.0" encoding="utf-8"?>
+<getProjectsResult xmlns:r="http://dev.rcware.eu/serialization/references" xmlns="http://dev.rcware.eu/scada/projects">
+    <projects>
+        <project id="2a7f1615-..." name="Weather" />
+        <project id="1b2623be-eaa4-4e29-8596-c66dd85d5643" name="SIMPLE_DEMO" />
+        <project id="5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0" name="PLYNOVA_KOTELNA" />
+        <project id="b9ad5380-..." name="CVUT_HERBERTOV" />
+        <project id="843855a2-..." name="PRVNI_KROKY" />
+    </projects>
+</getProjectsResult>
 </code>
@@ Line 349: / Line 322: @@
 <code javascript>
 {
- "cred": { "t": "xxxxxx" },
+ "cred": {
+  "n": "demo",
+  "p": "demo"
+ },
  "projId": "5abf8ca0-94ba-48df-8d3c-7ebe87a12fd0",
  "treeId": "Visual tree",
@@ Line 385: / Line 361: @@
   * **span:** sampling interval in seconds, default is 300 sec.
   * **zone:** time zone ('local' or 'utc') applied to parameters and output, default is 'local'.
-  * **doublesInterpolationMethod:** applied to double values (e.g., ''interp1''); other types use 'previous'.
-  * **interpolate_gaps_shorter_than:** interpolates missing value periods shorter than this parameter (in seconds).
   * **Returns:** ''data'' (NaN used for missing values), ''time'', ''dataInCell'' (useful for strings), and ''info''.
@@ Line 413: / Line 387: @@
 ==== setDataPointValue ====
 <code matlab>setDataPointValue(projGuid, dpGuid, value, buttonName)</code>
-Sets a datapoint value using a button (primarily the INIT button). Only numerical values are supported. Parameter ''buttonName'' is not mandatory; 'INIT' is used if undefined.
+Sets a datapoint value using a button. Only numerical values are supported. Parameter ''buttonName'' is not mandatory; 'INIT' is used if undefined.
-{{ :en:mervis-scada:init.png?direct&800 |}}
 **Example:**
@@ Line 424: / Line 396: @@
 newValue = 1;
-scada = ScadaClient('https://scada.mervis.info/','username','password');
+scada = ScadaClient('https://scada.mervis.info/','demo','demo');
 scada.setDataPointValue(projectId, dpGuid, newValue, buttonName)
 </code>