AMAGE REST API - Item Types

Wstęp/Kontekst

Context for operations on objects concerning element types (ElementType/Parameter/ParameterTemplate) in the AMAGE system, which should be extended with the appropriate method in the query.

rest/amage/v1/element-types

Struktury danych

Struktury i typy danych wykorzystywane w zapytaniach i odpowiedziach.

Result

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

Parameter type

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

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

Identifier Type

An enumeration element that specifies the type of the identifier (IdentifierType):

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

Element Types - API Operations

Element types - operations on element types. Type parameters are covered by additional methods.

Getting the number of item types

Method: GET
Path: /count
Generates: text/plain
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Returns the number of all element types in the system.

{
    123456
}

Get list of element types

Method: GET
Path: /list
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

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": "Item name",
"description": "Item description",
"icon": "",
"category": "Item category",
"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": "ID value",
            "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,

    "requiredParameters": true,
    "requiredParametersList": "RequiredParametersList",
    "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.

Getting the element type by UUID

Method: GET
Path: /get/by-uuid/{uuid}
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

UUID - element type identifier

The data returned is a single JSON object with an element type structure identical to the /list method.

Adding a new type of elements

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

Parametry:

ElementType - BodyContent - JSON structure identical to a single element from the /list method. The ID field will be replaced when saving the record

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

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.

Update element type

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

Parametry:

UUID - element type identifier
ElementType - BodyContent - JSON structure identical to a single element from the /list method. The ID/UUID field is ignored during update.

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

Removing an element type

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

Parametry:

uuid - UUID identifier of the element type

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

Deleting an item type may fail due to the item type being associated with other records in the system. In this case, an error will be returned with information about the problem.

Parameters - API operations

Separate API for parameters defining element types.

Number of parameters for a given element type

Method: GET
Path: /{element-type-uuid}/parameters/count
Generates: text/plain
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

element-type-uuid - element type UUID

Returns the number of all parameters for a given element type in the system.

{
    123456
}

List of parameters in a given element type

Method: GET
Path: /{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 - element type UUID
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 j/n structure. Parameter type explained in dictionary data.

[
  {
    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "name": "parameter",
    "description": "parameter description",
    "type": "STRING",
    "category": "tools",
    "expression": ".*",
    "defaultValue": "100",
    "unit": "pcs",
    "protocolData": ""
  }
]

Getting a single parameter for an element type

Method: GET
Path: /{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 - element type UUID
uuid - parameter identifier

The returned data is a JSON object with the same structure as the /list method for parameters.

Adding a new parameter to the element type

Method: PUT
Path: /{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 - element type UUID

In the query body, a JSON object with a parameter should be sent. The ID field will be replaced when writing the record. The JSON structure is identical to a single element from the /list method for parameters.

A response object is returned with the ID/UUID field of the newly created parameter.

Update parameter for element type

Metoda: POST
Path: /{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 - element type UUID
uuid - parameter identifier

In the query body, a JSON object with a parameter should be sent. The ID/UUID field will not be changed in the original object. The JSON structure is identical to a single element from the /list method for parameters.

A response object is returned with the ID/UUID field of the parameter being modified.

Removing a parameter from an element type

Method: GET
Path: /{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 - element type UUID
uuid - parameter identifier

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

Deleting a parameter for an item type may fail due to the record being related to other records in the system. In this case, an error will be returned with information about the problem.

Supplementing (adding) parameters for the element type from the parameter template

Metoda: POST
Path: /{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 - element type UUID
template-uuid - parameter template identifier

The operation adds new parameters to the existing parameters, which are in the parameter template. A result object with the operation status is returned.

Replacing parameters for an element type from a parameter template

Method: GET
Path: /{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 - element type UUID
template-uuid - parameter template identifier

The operation performs the removal of existing parameters and then the addition of new parameters, which are in the parameter template. A result object with the operation status is returned.

Parameter Templates - API Operations

We can refer to operations concerning parameter templates via API. Parameter templates are a set of parameters that can be used to supplement the parameters for an element type.

Number of parameter templates

Method: GET
Path: /parameter-templates/count
Generates: text/plain
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Returns the number of all parameter templates in the system.

{
    123456
}

List of parameter templates

Method: GET
Path: /parameter-templates/list
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

List of parameter templates

Method: GET
Path: /parameter-templates/list
Generuje: application/json
Wymaga: application/json, text/plain
Autoryzacja: podpis API (device-uuid, api-key, api-sign)

The query returns a list of parameter templates in the system. A list is returned that is consistent with the JSON format.

[
    {
        "id": 12345,
        "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
        "name": "Parameter template",
        "itemList": [
            {
                "id": 12345,
                "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
                "name": "Parameter",
                "description": "parameter description",
                "type": "STRING",
                "category": "Tools",
                "expression": ".*",
                "defaultValue": "100",
                "unit": "Pcs.",
                "protocolData": ""
            }
        ]
    }
]