access_via_api
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
access_via_api [2018/12/11 12:07] – [Getting current registers values] emozolyak | access_via_api [2023/03/02 10:53] (current) – [API usage examples] emozolyak | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | <WRAP center round tip 60%> | ||
+ | |||
+ | |||
====== Using API ====== | ====== Using API ====== | ||
Line 25: | Line 28: | ||
Content-Type: | Content-Type: | ||
+ | <WRAP center round important 60%> | ||
+ | Note that, if you are using another WebHMI as client (via [[Lua_API|cURL Lua]]' | ||
+ | Accept-Encoding: | ||
+ | </ | ||
+ | |||
Example of a connection list request: | Example of a connection list request: | ||
Line 518: | Line 526: | ||
} | } | ||
</ | </ | ||
+ | ==== Register' | ||
^ Register' | ^ Register' | ||
|**id**| int | Unique register id | | |**id**| int | Unique register id | | ||
Line 609: | Line 617: | ||
|3|Double Word | | |3|Double Word | | ||
|4|Unix Time | | |4|Unix Time | | ||
+ | |5|String | | ||
+ | |||
^Storage formats identifiers: | ^Storage formats identifiers: | ||
Line 624: | Line 634: | ||
To obtain entries from the register register, you must perform follwing GET request on a URL http:// | To obtain entries from the register register, you must perform follwing GET request on a URL http:// | ||
- | In the request headers, it is necessary to pass the API key, the boundaries of the time interval of interest, and a list of register identifiers. X-WH-START and X-WH-END are transmitted in UnixTime format. The register ID is passed by a comma-separated list in the X-WH-REG-IDS | + | In the request headers, it is necessary to pass the API key, the boundaries of the time interval of interest, and a list of register identifiers. X-WH-START and X-WH-END are transmitted in UnixTime format. The register ID is passed by a comma-separated list in the X-WH-REGISTERS |
X-WH-APIKEY: | X-WH-APIKEY: | ||
X-WH-START: 1422595501 | X-WH-START: 1422595501 | ||
X-WH-END: 1422599101 | X-WH-END: 1422599101 | ||
- | X-WH-REG-IDS: 8,10 | + | X-WH-REGISTERS: 8,10 |
| | ||
Also, in the headers, you must specify the desired data exchange format. Currently, only the JSONformat is supported. | Also, in the headers, you must specify the desired data exchange format. Currently, only the JSONformat is supported. | ||
Line 648: | Line 658: | ||
X-WH-START: 1422595501 | X-WH-START: 1422595501 | ||
X-WH-END: 1422599101 | X-WH-END: 1422599101 | ||
- | X-WH-REG-IDS: 8,10 | + | X-WH-REGISTERS: 8,10 |
Reply example: | Reply example: | ||
Line 883: | Line 893: | ||
X-WH-APIKEY: | X-WH-APIKEY: | ||
- | In the request headers, you must pass the connection IDs (IDs). Register values will be returned only from those connections whose ID are specified in the X-WH-CONNS header. ID should be separated by comma, without spaces. This allows you to request not all registers, but only a part. | + | In the request headers, you must pass the connection IDs (IDs). Register values will be returned only from those connections whose ID are specified in the X-WH-CONNECTIONS |
Example: | Example: | ||
- | X-WH-CONNS: 1,2 | + | X-WH-CONNECTIONS: 1,2 |
| | ||
In this example, register values for the ID=1 and ID=2 will be returned. | In this example, register values for the ID=1 and ID=2 will be returned. | ||
Line 906: | Line 916: | ||
Accept-Encoding: | Accept-Encoding: | ||
X-WH-APIKEY: | X-WH-APIKEY: | ||
- | X-WH-CONNS: 1,2 | + | X-WH-CONNECTIONS: 1,2 |
| | ||
Example of the response: | Example of the response: | ||
Line 1238: | Line 1248: | ||
|min_val |double |Minimal value of the Y axis| | |min_val |double |Minimal value of the Y axis| | ||
|max_val |double |Maximal value of the Y axis| | |max_val |double |Maximal value of the Y axis| | ||
+ | |||
+ | ===== Alert list ===== | ||
+ | |||
+ | To get a list of all alerts, you must perform a GET request on the URL like this: http:// | ||
+ | |||
+ | To obtain information about a particular alert, you must perform a following GET request on a URL ' | ||
+ | |||
+ | In the headers, it is necessary to pass API key. For example: | ||
+ | |||
+ | X-WH-APIKEY: | ||
+ | | ||
+ | Also, in the headers, you must specify the desired data exchange format. Currently, only the JSON format is supported. | ||
+ | |||
+ | Accept: application/ | ||
+ | Content-Type: | ||
+ | |||
+ | Example of query for the full graph list: | ||
+ | |||
+ | ***URL:** http:// | ||
+ | ***Method: | ||
+ | *Headers: | ||
+ | |||
+ | Accept: application/ | ||
+ | Content-Type: | ||
+ | Accept-Encoding: | ||
+ | X-WH-APIKEY: | ||
+ | |||
+ | Reply example: | ||
+ | < | ||
+ | [ | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | ] | ||
+ | </ | ||
+ | |||
+ | <WRAP center round info 60%> | ||
+ | To get information about currently active alerts, you can use [[current_alerts? | ||
+ | </ | ||
+ | |||
+ | |||
===== Image list ===== | ===== Image list ===== | ||
Line 1300: | Line 1374: | ||
To get data from graph log, it is necessary to run following GET-query for URL http:// | To get data from graph log, it is necessary to run following GET-query for URL http:// | ||
- | Also, instead of specifying the graph ID, you can send the X-WH-REGS header. It specifies, through the comma, the ID of the registers for which data is to be extracted. Example: | + | Also, instead of specifying the graph ID, you can send the X-WH-REGISTERS |
- | X-WH-REGS: 23,12,4 | + | X-WH-REGISTERS: 23,12,4 |
In the request headers, you must pass the API key, the boundaries of the time interval of interest (X-WH-START, | In the request headers, you must pass the API key, the boundaries of the time interval of interest (X-WH-START, | ||
Line 1624: | Line 1698: | ||
Content-Type: | Content-Type: | ||
| | ||
- | Consider an example of two events. Event number 1 is the parent event. It starts on the 5th second of every minute and ends on the 40th second of every minute. The log records data once for the entire event. The time of the beginning of the event and the last value of the interval register I60 are recorded in the log. Screenshots illustrate the setting of this event. | ||
- | {{:: | + | <WRAP center round info 80%> |
+ | Please refer for [[events]] chapter for more information. | ||
+ | </ | ||
- | {{:: | ||
- | |||
- | The second event is the child event for the first event. Therefore, it can only be executed when the first event is executed. In addition, the condition is limited so that it starts at the 25th second of every minute and ends at the 35th. Data for it is written to the log every 2 seconds. The current value of the I60 register is written to the log. Screenshots illustrate the setting of this event. | ||
- | |||
- | {{:: | ||
- | |||
- | {{:: | ||
- | |||
- | {{:: | ||
Example of getting date about event #1: | Example of getting date about event #1: | ||
Line 2106: | Line 2172: | ||
|**fontsize**| int |Font size, 1-5 | | |**fontsize**| int |Font size, 1-5 | | ||
|**regid**| int |ID of the source register for value | | |**regid**| int |ID of the source register for value | | ||
+ | |||
+ | |||
+ | |||
+ | ===== Managing recipes list ===== | ||
+ | |||
+ | |||
+ | To get a list of all recipes, you must perform a GET request on the URL like this: http:// | ||
+ | |||
+ | To obtain information about a particular recipe, you must perform a following GET request on a URL ' | ||
+ | |||
+ | In the headers, it is necessary to pass API key. For example: | ||
+ | |||
+ | X-WH-APIKEY: | ||
+ | |||
+ | Also, in the headers, you must specify the desired data exchange format. Currently, only the JSON format is supported. | ||
+ | |||
+ | Accept: application/ | ||
+ | Content-Type: | ||
+ | |||
+ | Example of a query for all recipes data: | ||
+ | |||
+ | ***URL:** http:// | ||
+ | ***Method: | ||
+ | *Headers: | ||
+ | |||
+ | Accept: application/ | ||
+ | Content-Type: | ||
+ | Accept-Encoding: | ||
+ | X-WH-APIKEY: | ||
+ | |||
+ | Response example: | ||
+ | < | ||
+ | [ | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | ] | ||
+ | </ | ||
+ | |||
+ | ^Block attributes: | ||
+ | |**id**| int |Unique recipe identifier | | ||
+ | |**title**| string |Title of recipe | | ||
+ | |**category**| string |Category of recipe | | ||
+ | |**description**| string |Description of recipe | | ||
+ | |**regs_values**| string |List of register values in following format: reg_id1%%^%%new_value%%|%%reg_id2%%^%%new_value%%|%%reg_id3%%^%%new_value | | ||
+ | |**allowed_for_roles**| string |Comma-separated role IDs who can access this recipe | | ||
+ | |**disabled**| int |Flag that shows if recipe is disabled | | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | To update a register values in particular recipe it's necessary to execute PUT-request on URL http:// | ||
+ | |||
+ | In the headers, it is necessary to pass API key. For example: | ||
+ | |||
+ | X-WH-APIKEY: | ||
+ | |||
+ | Also, in the headers, you must specify the desired data exchange format. Currently, only the [[https:// | ||
+ | |||
+ | |||
+ | Accept: application/ | ||
+ | Content-Type: | ||
+ | |||
+ | |||
+ | In the request body, the json-object with at least of property be passed. | ||
+ | < | ||
+ | {" | ||
+ | </ | ||
+ | |||
+ | Example of updating title and register values to the recipe with ID = 5: | ||
+ | |||
+ | ***URL**: http:// | ||
+ | ***Method**: | ||
+ | *Headers: | ||
+ | |||
+ | Accept: application/ | ||
+ | Content-Type: | ||
+ | Accept-Encoding: | ||
+ | X-WH-APIKEY: | ||
+ | |||
+ | Request body: | ||
+ | |||
+ | {" | ||
+ | |||
+ | If the request is valid, API will return HTTP-code 200. | ||
+ | |||
+ | ===== Getting meters log ===== | ||
+ | |||
+ | There is an option to use a register as a tolalizers for resources like water, has, heat, electricity etc. Then its current value together with hourly consumption will be stored in the database. | ||
+ | |||
+ | To obtain entries from the meters log, you must perform follwing GET request on a URL http:// | ||
+ | |||
+ | In the request headers, it is necessary to pass the API key, the boundaries of the time interval of interest, X-WH-START and X-WH-END are transmitted in UnixTime format. All meter registers will be returned, so X-WH-REGISTER header is omitted. For example: | ||
+ | |||
+ | X-WH-APIKEY: | ||
+ | X-WH-START: 1422595501 | ||
+ | X-WH-END: 1422599101 | ||
+ | | ||
+ | Also, in the headers, you must specify the desired data exchange format. Currently, only the JSON format is supported. | ||
+ | |||
+ | Accept: application/ | ||
+ | Content-Type: | ||
+ | |||
+ | Example of querying records from the register log: | ||
+ | |||
+ | ***URL**: http:// | ||
+ | ***Method**: | ||
+ | ***Headers**: | ||
+ | |||
+ | Accept: application/ | ||
+ | Content-Type: | ||
+ | Accept-Encoding: | ||
+ | X-WH-APIKEY: | ||
+ | X-WH-START: 1422595501 | ||
+ | X-WH-END: 1422599101 | ||
+ | |||
+ | Reply example: | ||
+ | |||
+ | < | ||
+ | [ | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | }, | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | ] | ||
+ | </ | ||
+ | |||
+ | The %%//%% are comments, they are absent in the real reponse. | ||
+ | |||
+ | ====== API usage examples ====== | ||
+ | |||
+ | * [[access_from_lua_to_webhmi_itself | Data access from WebHMI itself]] | ||
+ | * [[example_of_data_access_from_excel_via_api|Data access from Excel]] | ||
+ | * [[example_of_data_access_from_c_c|Data access from C/C++]] | ||
+ | * [[google_sheet_api_example|Data access from the Google Sheets]] | ||
+ | * [[Android demo application]] | ||
+ | * [[Android application via Chrome]] | ||
access_via_api.txt · Last modified: 2023/03/02 10:53 by emozolyak