Unit management

Manage Units

Finding units by filters with sorting and paging

get

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.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Available scopes:

: Needed to manage measurement units.

Path parameters

tenantstringRequired

The tenant name.

Query parameters

paramsstringOptional

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 a case of string values, the contains approach is taken (filtering by substrings).
In a 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 the default language is taken). For example, when Accept-Language is set to 'en', the request with parameter name=meter returns all units with name that contains meter in English. For example, in that case meter, kilometer and millimeter units are returned.
When Accept-Language header is set to * filtering by localized fields is possible only when fields contains a 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.

sortstringOptional

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's 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: name,factor:asc,metadata.createdAt:desc

pageNumbernumberOptional

The page number to be displayed.

Example: 1

pageSizenumberOptional

Number of units on a single page.

Default: 60

Header parameters

Accept-LanguagestringOptional

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-CountstringOptional

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

Example: true

Responses

200

The units were retrieved successfully.

application/json

400

Example response

application/json

401

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

Details will be provided in the response payload.

application/json

500

Unexpected server error

application/json

get

/unit-handling/{tenant}/units

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

Adding a new unit

post

Creates a new unit. After successful creation, the unit is 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.

Required scopes

unithandling.unit_manage

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Available scopes:

: Needed to manage measurement units.

Path parameters

tenantstringRequired

The tenant name.

Header parameters

Content-LanguagestringRequired

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

Example: fr

Body

codestringRequired

The unit code.

Example: g

nameone ofRequired

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

stringOptional

typestringRequired

The type of a unit.

Example: mass

symbolstringOptional

The symbol of a unit.

Example: °C

baseUnitbooleanRequired

The base unit flag.

Example: true

factornumberRequired

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

Example: 1

Responses

201

The unit has been successfully created.

application/json

400

Example response

application/json

401

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

Details will be provided in the response payload.

application/json

403

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

application/json

409

The unit already exists.

application/json

500

Unexpected server error

application/json

post

/unit-handling/{tenant}/units

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

Deleting units in bulk by codes

delete

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

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Available scopes:

: Needed to manage measurement units.

Path parameters

tenantstringRequired

The tenant name.

Responses

204

The units have been successfully deleted.

400

The units cannot be deleted due to no payload.

application/json

401

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

Details will be provided in the response payload.

application/json

403

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

application/json

500

Unexpected server error

application/json

delete

/unit-handling/{tenant}/units

DELETE /unit-handling/{tenant}/units HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Retrieving a unit by code

get

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.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Available scopes:

: Needed to manage measurement units.

Path parameters

unitCodestringRequired

The code of the unit.

Example: g

tenantstringRequired

The tenant name.

Header parameters

Accept-LanguagestringOptional

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7

Responses

200

Returns the given unit.

application/json

400

Example response

application/json

401

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

Details will be provided in the response payload.

application/json

404

The unit has not been found.

application/json

500

Unexpected server error

application/json

get

/unit-handling/{tenant}/units/{unitCode}

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

Updating a unit

put

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, the unit is 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.

Required scopes

unithandling.unit_manage

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Available scopes:

: Needed to manage measurement units.

Path parameters

unitCodestringRequired

The code of the unit.

Example: g

tenantstringRequired

The tenant name.

Header parameters

Content-LanguagestringRequired

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

Example: fr

Body

Responses

204

The unit has been updated successfully.

400

The unit cannot be updated due to an incorrect payload.

application/json

401

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

Details will be provided in the response payload.

application/json

403

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

application/json

404

The unit has not been found.

application/json

500

Unexpected server error

application/json

put

/unit-handling/{tenant}/units/{unitCode}

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

Deleting a specific unit

delete

Deletes a unit with a given code. After a successful deletion, the unit is not visible and executable for other parts of the system after 5 minutes.

Required scopes

unithandling.unit_manage

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Available scopes:

: Needed to manage measurement units.

Path parameters

unitCodestringRequired

The code of the unit.

Example: g

tenantstringRequired

The tenant name.

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.

application/json

403

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

application/json

404

The unit has not been found.

application/json

500

Unexpected server error

application/json

delete

/unit-handling/{tenant}/units/{unitCode}

DELETE /unit-handling/{tenant}/units/{unitCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

PreviousUnit Handling NextUnit conversion

Last updated 8 days ago

Was this helpful?

Good night

Finding units by filters with sorting and paging

Adding a new unit

Required scopes

Deleting units in bulk by codes

Required scopes

Retrieving a unit by code

Updating a unit

Required scopes

Deleting a specific unit

Required scopes