AMAGE REST API - Item Types

Introduction/Context

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

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

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

  • Requires: application/json, text/plain

  • Authorization: API signature (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

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

Getting the element type by 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 - 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

  • Path: /add

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • 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.

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.

Update element type

  • Method: POST

  • Path: /update/{uuid}

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • 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

  • Method: DELETE

  • Path: /delete/{uuid}

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • 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

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • 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

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

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

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • 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

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • 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

  • Method: POST

  • Path: /{element-type-uuid}/parameters/update/{uuid}

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

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

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • 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

  • Method: POST

  • Path: /{element-type-uuid}/parameters/append-from-template/{template-uuid}

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

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

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

  • 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

  • Requires: application/json, text/plain

  • Authorization: API signature (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

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (device-uuid, api-key, api-sign)

List of parameter templates

  • Method: GET

  • Path: /parameter-templates/list

  • Generates: application/json

  • Requires: application/json, text/plain

  • Authorization: API signature (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": ""
            }
        ]
    }
]