AMAGE REST API Interface - Execution Supervision
Introduction/Context
Context for operations on Supervision module objects in the AMAGE system, which should be extended with the appropriate method in the query.
-
rest/amage/v1/supervisions
Data structures
Structures and data types used in queries and responses.
Result:
The ID/UUID fields contain the identifier of the newly created or edited object. If the operation is performed correctly, the success field is set to true
. If an error occurs, the success field is set to false
, and the message field contains a description of the error. The error code then contains an HTTP code of the NOT_FOUND or BAD_REQUEST type. The BAD_REQUEST code is also returned in the query. Depending on the type of error during query processing, the error code may be different than the main query code returned. The query code will be BAD_REQUEST, and the internal code will be set to NOT_FOUND in the case when the query sets an object property to another object in the system. The JSON parameter will be correct (record UUID), but there will be no such record in the system. Therefore, the NOT_FOUND code will appear in the errorCode field. In the message
description field, a message informing what record was not found, and the main query error code will be BAD_REQUEST.
{
"id": 1,
"uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"success":true,
"errorCode":0,
"message":""
}
Source of information. Enumerated field as a comma-separated list of values. Available values:
-
FROM_DESKTOP,
-
FROM_MOBILE,
-
FROM_IDENTIFIER,
-
FROM_DIFFERENCE,
-
FROM_IMPORT,
-
FROM_WEB_SERVICE,
-
FROM_DATA_AGGREGATOR,
-
FROM_AUTOMATION
API operations
Getting the number of supervision items
-
Method:
GET
-
Path:
/count
-
Generates:
text/plain
-
Requires:
application/json
,text/plain
-
Authorization: API signature (device-uuid, api-key, api-sign)
Returns the number of all supervision items in the system.
{
123456
}
Downloading the list of supervised items
-
Method:
GET
-
Path:
/list
-
Generates:
application/json
-
Requires:
application/json
,text/plain
-
Authorization: API signature (device-uuid, api-key, api-sign)
Parametrs:
-
page
- RequestParam - page - counted from 1 -
size
- RequestParam - page size - number of records per page, we suggest limiting it to 1000 items. Depending on the API implementation, the value may be limited to a smaller number.
The returned data is an array of JSON objects with the structure:
{
"id": 12345,
"uuid": "a7de192f-e9c4-4ff9-9875-95f1144665c3",
"productUuid": "a7de192f-e9c4-4ff9-9875-95f1144665c3",
"active": true,
"stateTemplateUuid": "a7de192f-e9c4-4ff9-9875-95f1144665c3",
"stateTemplateItemUuid": "a7de192f-e9c4-4ff9-9875-95f1144665c3",
"progress": 100,
"currentCount": 10
}
In the case of downloading data from the system, the ID/UUID field will be populated in the returned structure with data from the system. The ID field is the identifier of the local database. The UUID field is a global identifier in the AMAGE system, which can serve as an identifier uniquely identifying an object in the system and in integrations between systems. |
Getting a supervision item by UUID
-
Method:
GET
-
Path:
/get/by-uuid/{uuid}
-
Generates:
application/json
-
Requires:
application/json
,text/plain
-
Authorization: API signature (device-uuid, api-key, api-sign)
Parametrs:
-
UUID - supervised element identifier
The data returned is a single JSON object with an element type structure identical to the /list
method.
Initializing a new supervision element
-
Method:
POST
-
Path:
/init/{product-uuid}/{template-uuid}
-
Generates:
application/json
-
Requires:
application/json
-
Authorization: API signature (device-uuid, api-key, api-sign)
Initializes a new supervision item. Requires the product UUID and the state template UUID. If a supervision for a given template exists for the given resource, then an operation result object is returned with the BAD_REQUEST code and information about a potential duplicate record.
Query content (body) is empty.
Query
/rest/amage/v1/supervisions/add/9cefca39-0d18-47ec-ab26-c694e5aec7ce/5de59aac-e704-424d-ab30-5d5d7693ff3c
Response
{
"id": 12345,
"uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"success":true,
"errorCode":0,
"message":""
}
Removing a supervision element
-
Method:
DELETE
-
Path:
/delete/{uuid}
-
Generates:
application/json
-
Requires:
application/json
-
Authorization: API signature (device-uuid, api-key, api-sign)
Parametrs:
-
UUID - supervised element identifier
Query content (body) is empty.
Query
/rest/amage/v1/supervisions/delete/f25e62ea-0100-4f4e-aad2-853cf48df2b9
Response
{
"uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"success":true,
"errorCode":0,
"message":""
}
Reading the supervision history record data
-
Method:
GET
-
Path:
/history/{uuid}
-
Generates:
application/json
-
Requires:
application/json
,text/plain
-
Authorization: API signature (device-uuid, api-key, api-sign)
Parametrs:
-
UUID - history entry identifier for the supervised item
The returned data is a JSON object with a structure:
{
"id": 12345,
"uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"invalid":false,
"timestamp":"2021-01-01T12:00:00",
"supervisionElementUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"userUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"supervisionStateTemplateItemUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"progress":100,
"addedCount":0,
"locationUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"mapShapeLatitude":50.0,
"mapShapeLongitude":20.0,
"mapShapeMapCode":"default",
"parameters":[
{
"id": 3456,
"parameterSettingUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"date": "2021-01-01T12:00:00",
"userUuid": "1c4066e6-cdd6-4903-803a-b6bffe689527",
"currentValue":"100.0",
"source":"FROM_WEBSERVICE"
}
]
}
In case of retrieving data from the system, the ID and UUID fields will be filled in the returned structure with data from the system. The ID field is the local database identifier. The UUID field is a global identifier in the AMAGE system, which can be used as an identifier that uniquely identifies an object in the system and in integrations between systems. |
Saving history to an existing supervised item
-
Method:
POST
-
Path:
/add-history/{uuid}
-
Generates:
application/json
-
Requires:
application/json
-
Authorization: API signature (device-uuid, api-key, api-sign)
Parametrs:
-
UUID - supervised element identifier
The query body should contain a JSON object with monitoring history data. The object has the following structure:
{
"invalid":false,
"timestamp":"2021-01-01T12:00:00",
"supervisionElementUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"userUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"supervisionStateTemplateItemUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"progress":100,
"addedCount":0,
"locationUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"mapShapeLatitude":50.0,
"mapShapeLongitude":20.0,
"mapShapeMapCode":"default",
"parameters":[
{
"id": -1,
"parameterSettingUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"date": "2021-01-01T12:00:00",
"userUuid": "1c4066e6-cdd6-4903-803a-b6bffe689527",
"currentValue":"100.0",
"source":"FROM_WEBSERVICE"
}
]
}
Query
/rest/amage/v1/supervisions/add-history/1c4066e6-cdd6-4903-803a-b6bffe689527
Response
{
"uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"success":true,
"errorCode":0,
"message":""
}
When saving data from the system, the ID field cannot be filled in. It is filled in when saving the record to the database and returned in the response structure. If the UUID field is provided, then such a value will be assigned to the record. The system does not check the uniqueness of the UUID within the structures or context of the entire system. If the UUID is not provided, the system will generate its own unique UUID. |
Editing supervision history
-
Method:
POST
-
Path:
/edit-history/{uuid}
-
Generates:
application/json
-
Requires:
application/json
-
Authorization: API signature (device-uuid, api-key, api-sign)
Parametrs:
-
UUID - supervision history identifier
Due to operations on existing data, changes in related parameters are not included in the edit. The parameters remain unchanged. We only modify the parameters of the main object of supervision history. |
The query body should contain a JSON object with monitoring history data. The object has the following structure:
{
"invalid":false,
"timestamp":"2021-01-01T12:00:00",
"supervisionElementUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"userUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"supervisionStateTemplateItemUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"progress":100,
"addedCount":0,
"locationUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
"mapShapeLatitude":50.0,
"mapShapeLongitude":20.0,
"mapShapeMapCode":"default"
}
Query
/rest/amage/v1/supervisions/edit-history/1c4066e6-cdd6-4903-803a-b6bffe689527
Response
{
"uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"success":true,
"errorCode":0,
"message":""
}
Deletion of supervision history
-
Method:
DELETE
-
Path:
/delete-history/{uuid}
-
Generates:
application/json
-
Requires:
application/json
-
Authorization: API signature (device-uuid, api-key, api-sign)
Parametrs:
-
UUID - supervision history identifier
Query content (body) is empty.
Query
/rest/amage/v1/supervisions/delete-history/1c4066e6-cdd6-4903-803a-b6bffe689527
Response
{
"uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
"success":true,
"errorCode":0,
"message":""
}
Examples
Sample Python code using the requests library to add supervision history.
#!/usr/bin/python3
import binascii
import hashlib
import requests
PARAM_SEPARATOR = ";"
def calc_api_sign(path, api_secret):
message_digest = hashlib.sha256()
message_digest.update(bytearray.fromhex(api_secret))
message_digest.update(PARAM_SEPARATOR.encode('utf-8'))
message_digest.update(path.encode('utf-8'))
return message_digest.digest()
def post_method(server_url, headers, path, json):
print(server_url + path)
url = server_url + path
response = requests.post(url, headers=headers, json=json)
print("received return code: {0}".format(response.status_code))
print("received data: {0}".format(response.text))
def get_header(path, content_type, accept):
headers = {
"Content-Type": content_type,
"Accept": accept,
"amage-device-uuid": device_uuid,
"amage-api-key": api_key,
"amage-api-sign": binascii.hexlify(calc_api_sign(path, api_secret)).decode()
}
return headers
server_url = "https://server.url/rest/amage/v1/"
device_uuid = "b0b135db-14f7-4d35-92d8-8357815185df"
api_key = "f4affb2db24b2b0903ad89ceeb622ece"
api_secret = "f4affb2db24b2b0903ad89ceeb622ede"
supervision_state_item_uuid = '1ba796f7-4a56-4ce1-ad6c-6d9c528974ad'
supervision_element_uuid = '1c4066e6-cdd6-4903-803a-b6bffe689527'
parameter_setting_uuid = '1c4066e6-cdd6-4903-803a-b6bffe689528'
request_path = "supervisions/add-history/" + supervision_element_uuid;
#ItemSource available values:
# FROM_DESKTOP,
# FROM_MOBILE,
# FROM_IDENTIFIER,
# FROM_DIFFERENCE,
# FROM_IMPORT,
# FROM_WEB_SERVICE,
# FROM_DATA_AGGREGATOR,
# FROM_AUTOMATION
1json = {
'invalid': False,
'timestamp': '2024-10-06T12:00:00',
'supervisionElementUuid': supervision_element_uuid,
'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185de',
'supervisionStateTemplateItemUuid': supervision_state_item_uuid,
'progress': 100,
'addedCount': 1,
'mapShapeLatitude': 0,
'mapShapeLongitude': 0,
'mapShapeMapCode': 'default',
'parameters': [
{
'date': '2024-10-06T12:00:00',
'parameterSettingUuid': 'e3588070-5ccf-47fa-aa9d-e7ca0b929d90',
'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185de',
'currentValue': '99',
'source': 'FROM_WEB_SERVICE'
}
]
}
post_method(server_url, get_header(request_path, "application/json", "application/json"), request_path, json)
Example execution
Example query results for adding supervision history.
json = {
'invalid': False,
'timestamp': '2024-10-06T12:00:00',
'supervisionElementUuid': supervision_element_uuid,
'userUuid': '75d2b25d-4698-48b9-bb62-7569ffb763fc',
'supervisionStateTemplateItemUuid': supervision_state_item_uuid,
'progress': 100,
'addedCount': 1,
'locationUuid': '75d2b25d-4698-48b9-bb62-7569ffb763fc',
'mapShapeLatitude': 0,
'mapShapeLongitude': 0,
'mapShapeMapCode': 'default',
'parameters': [
{
'date': '2024-10-06T12:00:00',
'parameterSettingUuid': 'e3588070-5ccf-47fb-aa9d-e7ca0b929d90',
'userUuid': '75d2b25d-4698-48b9-bb62-7569ffb763fc',
'currentValue': '99',
'source': 'FROM_WEB_SERVICE'
}
]
}
Incorrect location UUID:
httpd://server.url/rest/amage/v1/supervisions/add-history/1ba796f7-4a56-4ce1-ad6c-6d9c528974ad
received return code: 400
received data: {"id":null,"uuid":null,"success":false,"errorCode":400,"message":"Location not found with UUID: 75d2b25d-4698-48b9-bb62-7569ffb763fc"}
Invalid user UUID, no location:
/usr/bin/python3 example_supervision.py
http://localhost:8000/assetweb/rest/amage/v1/supervisions/add-history/1ba796f7-4a56-4ce1-ad6c-6d9c528974ad
received return code: 400
received data: {"id":null,"uuid":null,"success":false,"errorCode":400,"message":"User not found with UUID: 75d2b25d-4698-48b9-bb62-7569ffb763fc"}
Correct data:
1json = {
'invalid': False,
'timestamp': '2024-10-06T12:00:00',
'supervisionElementUuid': supervision_element_uuid,
'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185df',
'supervisionStateTemplateItemUuid': supervision_state_item_uuid,
'progress': 100,
'addedCount': 1,
'mapShapeLatitude': 0,
'mapShapeLongitude': 0,
'mapShapeMapCode': 'default',
'parameters': [
{
'date': '2024-10-06T12:00:00',
'parameterSettingUuid': 'e3588070-5ccf-47fb-aa9d-e7ca0b929d90',
'userUuid': 'b0b135db-14f7-4d35-92d8-8357815185df',
'currentValue': '99',
'source': 'FROM_WEB_SERVICE'
}
]
}
/usr/bin/python3 example_supervision.py
http://server.url/rest/amage/v1/supervisions/add-history/1ba796f7-4a56-4ce1-ad6c-6d9c528974ad
received return code: 200
received data: {"id":1000816683,"uuid":"d020d04c-756c-453e-8458-28590dc5c0fa","success":true,"errorCode":0,"message":""}
Process finished with exit code 0