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
  }
]

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.

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