Interfejs REST API AMAGE - typy elementów

Wstęp/Kontekst

Kontekst dla operacji na obiektach dotyczących typów elementów (ElementType/Parameter/ParameterTemplate) w systemie AMAGE, którą należy w zapytaniu rozszerzyć o odpowiednią metodę.

rest/amage/v1/element-types

Struktury danych

Struktury i typy danych wykorzystywane w zapytaniach i odpowiedziach.

Rezultat

W polach ID/UUID znajduje się identyfikator nowo utworzonego lub edytowanego obiektu. W przypadku poprawnego wykonania operacji pole success jest ustawiane na true. W przypadku wystąpienia błędu pole success jest ustawiane na false, a w polu message znajduje się opis błędu. Kod błędu zawiera wtedy kod HTTP typu NOT_FOUND lub BAD_REQUEST. Zwracany w zapytaniu wtedy jest również kod BAD_REQUEST. W zależności od typu błędu podczas przetwarzania zapytania kod błędu może być różny niż zwracany główny kod zapytania. Kod zapytania będzie BAD_REQUEST, a kod wewnętrzny będzie ustawiony na NOT_FOUND w przypadku takim, gdy zapytanie będzie ustawiało właściwość obiektu na inny obiekt w systemie. Parametr JSON będzie poprawny (UUID rekordu), ale takiego rekordu nie będzie w systemie. W związku z tym w polu errorCode pojawi się kod NOT_FOUND. W polu opisowym message komunikat informujący jakiego rekordu nie znaleziono, a główny kod błędu zapytania będzie wynosił BAD_REQUEST.

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

Typ parametru

Element wyliczeniowy, który określa typ parametru (ParameterType):

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

Typ identyfikatora

Element wyliczeniowy, który określa typ identyfikatora (IdentifierType):

BARCODE,
DATAMATRIX,
QRCODE,
RFID_LF,
RFID_HF,
RFID_MIFARE,
RFID_UHF,
BEACON

Typy elementów - Operacje API

Typy elementów - operacje dotyczące typów elementów. Parametry typów objęte są dodatkowymi metodami.

Pobieranie liczby typów elementów

Metoda: GET
Ścieżka: /count
Generuje: text/plain
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Zwraca liczbę wszystkich typów elementów w systemie.

{
    123456
}

Pobranie listy typów elementów

Metoda: GET
Ścieżka: /list
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

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.

Zwracane dane to obiekt JSON ze strukturą:

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

    "name": "Nazwa elementu",
    "description": "Opis elementu",
    "icon": "",
    "category": "Kategoria elementu",
    "catalogNumber": "123456",

    "manufacturerUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "orderNumber": "123456",
    "website": "https://www.example.com",

    "identifierList": [
        {
            "id": 12345,
            "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "value": "Wartość identyfikatora",
            "type": "STRING"
        }
    ],

    "warehouseIndex": "123456",
    "measurementUnitUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "unitPrice": 123.45,
    "currencyCode": "PLN",
    "taxUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "weight": 123.45,
    "area": 123.45,
    "minimumCount": 123.45,
    "maximumCount": 123.45,

    "requireParameters": true,
    "requiredParametersList": "Lista wymaganych parametrów",
    "requireIdentifiers": true
  }
]

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.

Pobranie typu elementu po UUID

Metoda: GET
Ścieżka: /get/by-uuid/{uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

UUID - identyfikator typy elementów

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

Dodanie nowego typu elementów

Metoda: PUT
Ścieżka: /add
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

ElementType - 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 typu elementów

Metoda: POST
Ścieżka: /update/{uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

UUID - identyfikator typu elementów
ElementType - 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.

Usunięcie typu elementów

Metoda: DELETE
Ścieżka: /delete/{uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

uuid - identyfikator UUID typu elementów

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

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

Parametry - operacje API

Osobne API dotyczące parametrów określających typy elementów.

Liczba parametrów danego typu elementów

Metoda: GET
Ścieżka: /{element-type-uuid}/parameters/count
Generuje: text/plain
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

element-type-uuid - UUID typu elementów

Zwraca liczbę wszystkich parametrów dla danego typu elementów w systemie.

{
    123456
}

Lista parametrów w danym typie elementów

Metoda: GET
Ścieżka: /{element-type-uuid}/parameters/list
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

element-type-uuid - UUID typu elementów
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.

Zwracane dane to obiekt JSON ze strukturą j/n. Typ parametru wyjaśniony w danych słownikowych.

[
  {
    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "name": "Parametr",
    "description": "opis parametru",
    "type": "STRING",
    "category": "Narzędzia",
    "expression": ".*",
    "defaultValue": "100",
    "unit": "Szt.",
    "protocolData": ""
  }
]

Pobranie pojedynczego parametr dla typu elementów

Metoda: GET
Ścieżka: /{element-type-uuid}/parameters/get/by-uuid/{uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

element-type-uuid - UUID typu elementów
uuid - identyfikator parametru

Zwracane dane to obiekt JSON ze strukturą tożsamą z metodą /list dla parametrów.

Dodanie nowego parametru do typu elementów

Metoda: PUT
Ścieżka: /{element-type-uuid}/parameters/add
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

element-type-uuid - UUID typu elementów

W ciele zapytania należy przesłać obiekt JSON z parametrem. Pole ID zostanie zastąpione podczas zapisu rekordu. Struktura JSON tożsama z pojedynczym elementem z metody /list dla parametrów.

Zwracany jest obiekt odpowiedzi z polem ID/UUID nowo utworzonego parametru.

Aktualizacja parametru dla typu elementów

Metoda: POST
Ścieżka: /{element-type-uuid}/parameters/update/{uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

element-type-uuid - UUID typu elementów
uuid - identyfikator parametru

W ciele zapytania należy przesłać obiekt JSON z parametrem. Pole ID/UUID nie będą zmieniane w oryginalnym obiekcie. Struktura JSON tożsama z pojedynczym elementem z metody /list dla parametrów.

Zwracany jest obiekt odpowiedzi z polem ID/UUID modyfikowanego parametru.

Usunięcie parametru z typu elementów

Metoda: GET
Ścieżka: /{element-type-uuid}/parameters/delete/{uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

element-type-uuid - UUID typu elementów
uuid - identyfikator parametru

Zwracane dane to obiekt odpowiedzi z polem ID/UUID usuwanego parametru dla typu elementów.

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

Uzupełnienie (dodanie) parametrów dla typu elementu z szablonu parametrów

Metoda: POST
Ścieżka: /{element-type-uuid}/parameters/append-from-template/{template-uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

element-type-uuid - UUID typu elementów
template-uuid - identyfikator szablonów parametru

Operacja wykonuje dodanie do istniejących parametrów, nowych parametrów, które znajdują się w szablonie parametrów. Zwracany jest obiekt rezultatu ze statusem operacji.

Zamiana parametrów dla typu elementu z szablonu parametrów

Metoda: GET
Ścieżka: /{element-type-uuid}/parameters/replace-from-template/{template-uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

element-type-uuid - UUID typu elementów
template-uuid - identyfikator szablonów parametru

Operacja wykonuje usunięcie istniejących parametrów, a następnie dodanie nowych parametrów, które znajdują się w szablonie parametrów. Zwracany jest obiekt rezultatu ze statusem operacji.

Szablony parametrów - operacje API

Do operacji dotyczących szablonów parametrów możemy odwołać się poprzez API. Szablony parametrów są zbiorem parametrów, które mogą być wykorzystane do uzupełnienia parametrów dla typu elementu.

Liczba szablonów parametrów

Metoda: GET
Ścieżka: /parameter-templates/count
Generuje: text/plain
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Zwraca liczbę wszystkich szablonów parametrów w systemie.

{
    123456
}

Lista szablonów parametrów

Metoda: GET
Ścieżka: /parameter-templates/list
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Lista szablonów parametrów

Metoda: GET
Ścieżka: /parameter-templates/list
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Zapytanie zwraca listę szablonów parametrów w systemie. Zwracana jest lista zgodna z formatem JSON.

[
    {
        "id": 12345,
        "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
        "name": "Szablon parametrów",
        "itemList": [
            {
                "id": 12345,
                "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
                "name": "Parametr",
                "description": "opis parametru",
                "type": "STRING",
                "category": "Narzędzia",
                "expression": ".*",
                "defaultValue": "100",
                "unit": "Szt.",
                "protocolData": ""
            }
        ]
    }
]