Unit management
Was this helpful?
Was this helpful?
Manage Units
The tenant name.
testtenant
DELETE /unit-handling/{tenant}/units HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
No content
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.
The code of the unit.
g
The tenant name.
testtenant
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.
fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
GET /unit-handling/{tenant}/units/{unitCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
{
"code": "kg",
"name": "kilogram",
"type": "mass",
"baseUnit": true,
"factor": 1,
"metadata": {
"version": 1
}
}
The code of the unit.
g
The tenant name.
testtenant
DELETE /unit-handling/{tenant}/units/{unitCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
No content
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.
The tenant name.
testtenant
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 with
namethat contains
meterin English. For example, in that case
meter,
kilometerand
millimeter` 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.
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.
name,factor:asc,metadata.createdAt:desc
The page number to be displayed.
1
Number of units on a single page.
60
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.
fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
Total count flag. If set to true X-Total-Count header is returned.
true
GET /unit-handling/{tenant}/units HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
[
{
"code": "g",
"name": "gram",
"type": "mass",
"baseUnit": true,
"factor": 1,
"metadata": {
"version": 2,
"createdAt": "2021-10-25T10:59:24.385Z",
"modifiedAt": "2021-10-25T10:59:24.385Z"
}
},
{
"code": "ug",
"name": "microgram",
"type": "mass",
"symbol": "µg",
"baseUnit": false,
"factor": 0.000001,
"metadata": {
"version": 1,
"createdAt": "2021-10-25T10:59:24.385Z",
"modifiedAt": "2021-10-25T10:59:24.385Z"
}
}
]
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.
unithandling.unit_manage
The tenant name.
testtenant
The Content-Language request HTTP header defines language(s) of the payload.
fr
The unit code.
g
The name of the unit in the form of map (language, value) or string.
The type of unit.
mass
The symbol of unit.
°C
The base unit flag.
true
The conversion factor. The factor value must be greater than zero.
1
POST /unit-handling/{tenant}/units HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Language: fr
Content-Type: application/json
Accept: */*
Content-Length: 86
{
"code": "kg",
"name": "kilogram",
"type": "mass",
"baseUnit": true,
"symbol": "kg",
"factor": 1
}
{
"code": "text"
}
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.
unithandling.unit_manage
The code of the unit.
g
The tenant name.
testtenant
The Content-Language request HTTP header defines language(s) of the payload.
fr
PUT /unit-handling/{tenant}/units/{unitCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Language: fr
Content-Type: application/json
Accept: */*
Content-Length: 97
{
"code": "kg",
"name": "kilogram",
"type": "mass",
"baseUnit": true,
"factor": 1,
"metadata": {
"version": 1
}
}
No content