AMAGE REST API - Resources/Parameters

Introduction/Context

Context for operations on resource module objects (Structure) in the AMAGE system, which should be extended with the appropriate method in the query.

rest/amage/v1/assets

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":""
}

Parameter type. An enumeration element that specifies the type of the parameter (ParameterType):

STRING,
FLOAT,
INTEGER,
ENUM,
DATETIME,
DATE,
TIME

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

Typ identyfikatora

BARCODE,
DATAMATRIX
QRCODE
RFID_LF
RFID_HF
RFID_MIFARE
RFID_UHF
BEACON

Typ załącznika:

TEXT("txt")
HTML("html", "htm")
SPEECH("spc")
AUDIO("wav", "mp2", "mp3")
VIDEO("avi", "mpeg", "mp4", "mov")
PHOTO("jpg", "jpeg", "png", "bmp", "gif")
PDF("pdf")
OFFICE("doc", "docx", "xls", "xlsx", "xlsm", "odt", "ods")
MODEL3D("j3o", "obj")
IFC("ifc")
BINARY()

API operations

Pobieranie liczby zasobów/produktów

Method: GET
Path: /count
Generates: text/plain
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Zwraca liczbę wszystkich zasobów w systemie.

{
    123456
}

Pobranie listy zasobów

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 a JSON object with a structure:

{
    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "globalId": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "ifcTag": "1sd3df3d3dfd",

    "name": "Nazwa elementu",
    "serialNumber": "123456",
    "inventoryNumber": "123456",
    "count": 123.45,
    "note": "Notatka",

    "manufacturerUuid": "3198ca39-5e08-49b4-b825-11e3e2682f8c",
    "parentUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "typeUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "groupUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "locationUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "objectStateUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",

    "mapShapeLatitude": 123.45,
    "mapShapeLongitude": 123.45,
    "mapShapeMapCode": "default",

    "identifierList": [
        {
            "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "value": "P1234-445644",
            "type": "DATAMATRIX"
        }
    ],

    "attachmentList": [
        {
            "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "fileName": "plik.pdf",
            "attachmentType": "PDF",
            "hash": "c1534f7c2e65f4b93e284c6f878c1ba1"
        }
    ],

    "parameterSettingList": [
        {
            "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "parameterName": "parametr",
            "parameterUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "value": "Testowa wartość",
            "availability": true,
            "userUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "timestamp": "2021-01-01T12:00:00"
        }
    ],

    "contractUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "contractScopeUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "customerUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "recipientUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "dateOfProduction": "2021-01-01T12:00:00",
    "dateOfSale": "2021-01-01T12:00:00",
    "dateOfCommissioning": "2021-01-01T12:00:00",
    "warrantyExpirationDate": "2021-01-01T12:00:00",
    "warrantyPeriod": 123,
    "customWarranty": true,

    "equipmentObjectStateUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "equipmentEnabled": true,
    "equipmentOwnerUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "equipmentHolderUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "equipmentRequesterUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "equipmentCheckerUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "equipmentValidTillDate": "2021-01-01T12:00:00",
    "equipmentTestingLaboratoryUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "equipmentValidationDocument": "Dokument.pdf",
    "equipmentValidationNotes": "Notatka"

}

Identifier:

{

    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "value": "X-234-222",
    "type": "DATAMATRIX"
}

Attachment:

{

    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "fileName": "plik.pdf",
    "attachmentType": "PDF",
    "hash": "c1534f7c2e65f4b93e284c6f878c1ba1"
}

ParameterSetting:

{

    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "parameterName": "parametr",
    "parameterUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "value": "Testowa wartość",
    "availability": true,
    "userUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "timestamp": "2021-01-01T12:00:00"
}

Pobranie zasobu/produktu po 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 - identyfikator zasobu/produktu

Zwracane dane to pojedynczy obiekt JSON ze strukturą zasobu tożsamą z metodą /list.

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.

Dodanie nowego zasobu

Method: PUT
Path: /add
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

ProductDto - BodyContent - struktura JSON tożsama z pojedynczym elementem z metody /list. Pole ID zostanie zastąpione podczas zapisu rekordu

The data returned is a response object with the ID/UUID field of the newly created item type.

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.

Aktualizacja zasobu/produktu

Method: POST
Path: /update/{uuid}
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

UUID - identyfikator zasobu/produktu
ProductDto - BodyContent - struktura JSON tożsama z pojedynczym elementem z metody /list. Pole ID/UUID zostają zignorowane podczas aktualizacji.

The data returned is a response object with the ID/UUID field of the item type being modified.

W przypadku tej metody próba zmiany typu elementu się nie powiedzie. Wykorzystaj metodę /update-type/{uuid}/to/{element-type-uuid} do zmiany typu elementu, która zajmie się procedurą połączenia parametrów pochodzących ze starego i nowego typu elementów. Ma to na celu uniknięcie problemu związanego z utratą danych parametrów po zmianie typu elementu.

W przypadku aktualizacji listy identyfikatorów, parametrów i załączników system sprawdza istnienie danego obiektu - za pomocą identyfikatora UUID w liście elementów zasobu. Jeśli już istnieje, to jest aktualizowany lub pomijany w dodawaniu.

Aktualizacja typu elementu

Method: POST
Ścieżka: /update-type/{uuid}/to/{element-type-uuid}
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

uuid - identyfikator zasobu/produktu
element-type-uuid - identyfikator UUID nowego typu elementów

Operacja dedykowana specjalnie dla zmiany typu elementu dla danego zasobu. Wyciągnięta ze standardowej procedury /update ze względu na konieczność operowania na parametrach/ustawieniach parametrów w powiązanych rekordach. Aplikacja w trakcie wykonywania tej operacji przeprowadza procedurę POŁĄCZENIA parametrów istniejących w nowym typie elementów ORAZ parametrów ze starego typu elementu. Spowodowane to jest chęcią zachowania pełnej historii zmian ustawień parametrów pomiędzy zmianą typów. W przeciwnym przypadku istniałaby możliwość usunięcia historii zmiany parametrów zasobu w przypadku zmiany typu elementu.

Realizowane działania:

Ustawienia parametrów w oryginalnym zasobie (przed zmianą) są przepisywane do nowego zasobu (po zmianie)
Jeśli w nowym typie elementów ISTNIEJE parametr o takiej samej nazwie jak w oryginalnym typie elementów, to wartość ustawienia parametru z oryginalnego zasobu jest przepisywana do nowego zasobu (zamieniane jest wskazanie na parametr w nowym typie)
Jeśli w starym typie istniał parametr np. "długość", a w nowym typie elementów nie jest on dostępny, to procedura automatycznie DODA ten parametr do nowego typu elementów i powiąże go z ustawieniem parametru z oryginalnego zasobu
Nowe ustawienia parametrów są ustawiane zgodnie z definicją domyślnych wartości w nowym typie.

Taka operacja pozwala na zachowanie pełnej historii zmian parametrów zasobu w przypadku zmiany typu elementu. Użytkownik za pomocą dodatkowych operacji dotyczących określonych ustawień parametrów może zaktualizować wartości lub je usunąć, ale z pełną kontrolą nad historią zmian.

Usunięcie zasobu

Method: DELETE
Path: /delete/{uuid}
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

uuid - identyfikator UUID zasobu/produktu

Zwracane dane to obiekt odpowiedzi z polem ID/UUID usuwanego zasobu/produktu.

Usunięcie zasobu może się nie powieść ze względu na powiązanie zasobu z innymi rekordami w systemie. W takim przypadku zwrócony zostanie błąd z informacją dotyczącą problemu.

Reading the parameter setting value

Method: GET
Path: /parametersetting/{uuid}
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

UUID - parameter settings identifier in the resource

The returned data is a JSON object with a structure:

{
    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "parameter": {
        "id": 34567,
        "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
        "name": "parameter",
        "description": "parameter description",
        "category": "parameter category",
        "type": "STRING"
    },
    "value": "Test value",
    "availability": true,
    "userUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "timestamp": "2021-01-01T12:00:00"
}

Saving history to existing parameter setting

Method: POST
Path: /add-parametersetting-history/{uuid}
Generates: application/json
Requires: application/json
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

UUID - parameter settings identifier

In the query body, you should include a JSON object with the parameter history data. The object has the structure:

{
    "date": "2021-01-01T12:00:00",
    "parameterSettingUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "userUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "currentValue": "TestValue",
    "source": "FROM_WEB_SERVICE"
}

Query

/rest/amage/v1/assets/add-parametersetting-history/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

{
    "id": 12345,
    "uuid":"f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success":true,
    "errorCode":0,
    "message":""
}