Unit Handling Service

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

Define and manage various unit systems, including metric, imperial, USC, and custom in which your products may be sold.

Key Features:

  • Create unit types for length, mass, quantity and volume
  • Create and manage units per type and define the conversation between them
  • Convert units
  • Unicode unit symbol handling and localized names

Key Benefits:

  • Highly flexible unit management system that supports widely used unit systems such as metric, imperial or USC
  • Unit systems can exist in four different types: length, mass, quantity and volume
  • Products can be sold flexibly by defined units rather than by piece only - for example, 50 meters of a steel tube, 250 liters of liquid lubricants, or 250 grams of fresh-cut cheese

Unit management

Manage Units

Adding a new unit

Creates a new unit. After successful creation, unit will be visible and executable for other parts of the system after 5 minutes.

  • If the Content-Language is set to * the request body payload should contain localized fields not as a string, but as a map in format: key:value, where the key is the language code and value is the translation.

Please see the example (Unit with name as a map) in Request body section.

Required scopes

  • unithandling.unit_manage
SecurityOAuth2
Request
path Parameters
tenant
required
string

The tenant name.

Example: testtenant
header Parameters
Content-Language
required
string

The Content-Language request HTTP header defines language(s) of the payload.

Example: fr
Request Body schema: application/json
code
required
string

The unit code.

required
string or object

The name of the unit in the form of map (language, value) or string.

type
required
string

The type of unit.

symbol
string

The symbol of unit.

baseUnit
required
boolean

The base unit flag.

factor
required
number

The conversion factor. The factor value must be greater than zero.

Responses
201

The unit has been successfully created.

400

Example response

401

Given request is unauthorized - the authorization token is invalid or has expired.

Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

409

The unit already exists.

500

Unexpected server error

post/{tenant}/units
Request samples
application/json
{
  • "code": "kg",
  • "name": "kilogram",
  • "type": "mass",
  • "baseUnit": true,
  • "symbol": "kg",
  • "factor": 1
}
Response samples
application/json
{
  • "code": "string"
}

Finding units by filters with sorting and paging

Retrieves a list of units conforming with the given filters. Supports sorting and paging.

  • If the Accept-Language is set to * each internationalized field is returned as a map that contains all of translations in a format of key:value pairs, where the key is the language code and value is the translation.
  • The Accept-Language can contain the priority list of languages which should be returned. Always one language is returned as a single string field. Example: 'fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7'
  • If the Accept-Language header is empty default language defined in the Configuration service is taken.
  • If the unit name matches none of the specified languages, an empty string is returned in the name field.

Please, see the examples below.

SecurityOAuth2
Request
path Parameters
tenant
required
string

The tenant name.

Example: testtenant
query Parameters
params
string

Note: params is not a name of query param. Any API model field can be taken as a filtering parameter.

Filtering can be done by each field available in API. Filtering by multiple fields is also allowed. In that case, fields are aggregated with AND logic operator. In the case of string values, the contains approach is taken (filtering by substrings). In the case of boolean and number fields, the equals approach is taken.

Filtering query params examples:

  • type=mass - all units with type that contains mass are returned. For example, in that case all mass units will be returned.
  • type=a - all units with type that contains a are returned. For example, in that case all mass and distance units are returned.
  • factor=1 - all units with factor that equals 1 are returned.
  • baseUnit=true - all units with baseUnit that equals true are returned.
  • type=mass&name=gram - all units with type that contains mass AND name that contains gram are returned. For example, in that case kilogram, gram, decagram units are returned.

Filtering by localized fields:

  • Filtering by localized fields without language key is possible only when Accept-Language header with correct language is provided or when it is not set at all (in that case default language is taken). For example, when Accept-Language' is set to 'en', the request with parameter name=meterreturns all units withnamethat containsmeterin English. For example, in that casemeter, kilometerandmillimeter` units are returned.

  • When Accept-Language header is set to * filtering by localized fields is possible only when fields contains language key. For example, when Accept-Language is set to '*', the request with parameter name.en=meter returns all units with name.en that contains meter in English. For example, in that case meter, kilometer and millimeter units are returned.

Example: params=
sort
string

Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case. Sorting by name parameter works properly only if the Accept-Language header is set to a specific language or is empty with default language specified in the configuration service.

Example: sort=name,factor:asc,metadata.createdAt:desc
pageNumber
number

The page number to be displayed.

Example: pageNumber=1
pageSize
number
Default: 60

Number of units on a single page.

header Parameters
Accept-Language
string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, English language is returned. It can be a priority list working as a fallback mechanism.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
X-Total-Count
string

Total count flag. If set to true X-Total-Count header is returned.

Example: true
Responses
200

The units were retrieved successfully.

400

Example response

401

Given request is unauthorized - the authorization token is invalid or has expired.

Details will be provided in the response payload.

500

Unexpected server error

get/{tenant}/units
Request samples 
Response samples 
application/json
list containing localized units


[
  • {
    },
  • {
    }
]
Deleting units in bulk by codes
Deletes the units with the given codes. After successful deletion, units will not be visible and executable for other parts of the system after 5 minutes.


The codes are defined in the request body as an array of strings.


Example: ["g", "kg", "dag", "test"]




Required scopes


    

  • unithandling.unit_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
The tenant name.


 
 Example:  testtenant
Responses 
204
The units have been successfully deleted.


400
The units cannot be deleted due to no payload.


401
Given request is unauthorized - the authorization token is invalid or has expired.


Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


500
Unexpected server error


delete/{tenant}/units
Request samples 
Response samples 
application/json
{
  • "message": "Bad Request",
  • "_links": {
    },
  • "_embedded": {
    }
}
Retrieving unit by code
Retrieves the unit with the given code.


    

  • If the Accept-Language is set to * each internationalized field is returned as a map that contains all of translations in a format of key:value pairs, where the key is the language code and value is the translation.
    • 

  • The Accept-Language can contain the priority list of languages which should be returned. Always one language is returned as a single string field.
    • 

  • If the Accept-Language header is empty default language defined in the Configuration service is taken.
    • 

  • If the unit name matches none of the specified languages, an empty string is returned in the name field.
    • 



Please, see the examples below.


SecurityOAuth2 
Request 
path Parameters
unitCode
required
string
The code of the unit.


 
 Example:  g
tenant
required
string
The tenant name.


 
 Example:  testtenant
header Parameters
Accept-Language
string
The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, English language is returned. It can be a priority list working as a fallback mechanism.


 
 Example:  fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
Responses 
200
Returns the given unit.


400
Example response


401
Given request is unauthorized - the authorization token is invalid or has expired.


Details will be provided in the response payload.


404
The unit has not been found.


500
Unexpected server error


get/{tenant}/units/{unitCode}
Request samples 
Response samples 
application/json
{
  • "code": "kg",
  • "name": "kilogram",
  • "type": "mass",
  • "baseUnit": true,
  • "factor": 1,
  • "metadata": {
    }
}
Deleting a specific unit
Deletes the unit with the given code. After successful deletion, unit will not be visible and executable for other parts of the system after 5 minutes.




Required scopes


    

  • unithandling.unit_manage
    • 



SecurityOAuth2 
Request 
path Parameters
unitCode
required
string
The code of the unit.


 
 Example:  g
tenant
required
string
The tenant name.


 
 Example:  testtenant
Responses 
204
The unit has been successfully deleted.


401
Given request is unauthorized - the authorization token is invalid or has expired.


Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
The unit has not been found.


500
Unexpected server error


delete/{tenant}/units/{unitCode}
Request samples 
Response samples 
application/json
{
  • "fault": {
    }
}
Update unit
Updates an existing unit. Optimistic locking is applied to prevent update races when unit in
the payload contains the optional version field. After successful update, unit will be visible and executable for other parts of the system after 5 minutes.


    

  • If the Content-Language is set to *
the request body payload should contain localized fields not as a string,
but as a map in format: key:value, where the key is the language code and value is the translation.
    • 



Please see the example (Unit with name as a map) in Request body section.




Required scopes


    

  • unithandling.unit_manage
    • 



SecurityOAuth2 
Request 
path Parameters
unitCode
required
string
The code of the unit.


 
 Example:  g
tenant
required
string
The tenant name.


 
 Example:  testtenant
header Parameters
Content-Language
required
string
The Content-Language request HTTP header defines language(s) of the payload.


 
 Example:  fr
Request Body schema: application/json
code
required
string
The unit code.


 
required
string or object
The name of the unit in the form of map (language, value) or string.


 
type
required
string
The type of unit.


 
symbol
string
The symbol of unit.


 
baseUnit
required
boolean
The base unit flag.


 
factor
required
number
The conversion factor. The factor value must be greater than zero.


 
object (UpdateUnitMetadata) 
The metadata of the unit.


 
Responses 
204
The unit has been updated successfully.


400
The unit cannot be updated due to an incorrect payload.


401
Given request is unauthorized - the authorization token is invalid or has expired.


Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
The unit has not been found.


500
Unexpected server error


put/{tenant}/units/{unitCode}
Request samples 
application/json
{
  • "code": "kg",
  • "name": "kilogram",
  • "type": "mass",
  • "baseUnit": true,
  • "factor": 1,
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "There is a validation error. Please check the details.",
  • "details": [
    ]
}
Unit conversion
Convert Units


Fetching conversion factor
Calculates conversion factor for the given pair of units.


SecurityOAuth2 
Request 
path Parameters
tenant
required
string
The tenant name.


 
 Example:  testtenant
Request Body schema: application/json
commandUuid
string
 
required
object (ConversionFactorInput) 
The input payload.


 
Responses 
201
The factor has been successfully calculated.


400
The conversion factor cannot be fetched due to wrong parameters.


401
Given request is unauthorized - the authorization token is invalid or has expired.


Details will be provided in the response payload.


404
At least one of the specified units cannot be found.


500
Unexpected server error


put/{tenant}/units/conversion-factor-commands
Request samples 
application/json
{
  • "commandUuid": "string",
  • "input": {
    }
}
Response samples 
application/json
{
  • "commandUuid": "e948a54d-ffeb-405a-9614-c68406274554,",
  • "input": {
    },
  • "output": {
    }
}
Converting unit
Converts the source unit to a target unit.


SecurityOAuth2 
Request 
path Parameters
tenant
required
string
The tenant name.


 
 Example:  testtenant
Request Body schema: application/json
commandUuid
string
 
required
object (ConversionInput) 
The input payload.


 
Responses 
201
The unit has ben successfully converted.


400
The unit cannot be converted due to wrong parameters.


401
Given request is unauthorized - the authorization token is invalid or has expired.


Details will be provided in the response payload.


404
At least one of the specified units cannot be found.


500
Unexpected server error


put/{tenant}/units/convert-unit-commands
Request samples 
application/json
{
  • "commandUuid": "string",
  • "input": {
    }
}
Response samples 
application/json
{
  • "commandUuid": "83ddc478-89d7-48e1-8b6c-527f4c67fb56",
  • "input": {
    },
  • "output": {
    }
}
Type management
Read Units


Retrieving all unit types
Retrieves list of all unit types present in the database.


SecurityOAuth2 
Request 
path Parameters
tenant
required
string
The tenant name.


 
 Example:  testtenant
Responses 
200
All unit types retrieved successfully.


401
Given request is unauthorized - the authorization token is invalid or has expired.


Details will be provided in the response payload.


500
Unexpected server error


get/{tenant}/types
Request samples 
Response samples 
application/json
[
  • "length",
  • "mass",
  • "quantity",
  • "volume"
]