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
Ścieżka: /count
Generuje: 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
Ścieżka: /list
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

page - RequestParam - strona - liczona od 1
size - RequestParam - rozmiar strony - liczba rekordów na stronie, sugerujemy ograniczenie do 1000 elementów. W zależności od implementacji API, wartość może być ograniczona do mniejszej liczby.

The returned data is a JSON object with the 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
Ścieżka: /get/by-uuid/{uuid}
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

UUID - identyfikator zasobu/produktu

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

W przypadku pobierania danych z systemu pole ID, UUID będą w zwracanej strukturze wypełnione danymi pochodzącymi z systemu. Pole ID to identyfikator lokalnej bazy danych. Pole UUID to identyfikator globalny w systemie AMAGE, który może służyć jako identyfikator jednoznacznie identyfikujący obiekt w systemie i w integracjach pomiędzy systemami.

Dodanie nowego zasobu

Metoda: PUT
Ścieżka: /add
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

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

Zwracane dane to obiekt odpowiedzi z polem ID/UUID nowo utworzonego typu elementów.

W przypadku zapisu danych z systemu pole ID nie może być wypełnione. Zostaje ono uzupełnione podczas zapisu rekordu do bazy danych i zwrócone w strukturze odpowiedzi. Jeśli pole UUID zostanie podane, to taka wartość zostanie przypisana do rekordu. System nie sprawdza unikalności UUID w ramach struktur lub kontekstu całego systemu. Jeśli UUID nie zostanie podane, to system wygeneruje własne unikalne UUID.

Aktualizacja zasobu/produktu

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

Parameters:

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

Zwracane dane to obiekt odpowiedzi z polem ID/UUID modyfikowanego typu elementów.

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)

Parameters:

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

Metoda: DELETE
Ścieżka: /delete/{uuid}
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parameters:

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)

Parameters:

UUID - parameter settings identifier in the resource

The returned data is a JSON object with the 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)

Parameters:

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