How do I transmit the unit of measurement data via a Rest API?
Question
Application Type
Reactive

Hello everyone, I have written an app for sample management in which, among other things, measurement data is also stored. The data can be called via a Rest API. Everything works as desired.

Now I'm wondering if there is a recommendation on how to send the corresponding unit in addition to the measured value via the Rest API.

Example: I can currently save the preheating temperature and preheating time of a sample in the app, for example. If I now retrieve this measured value via the Rest API, I receive the following response:

{
"Result": {
"Success": true,
"ErrorMessage": ""
},
"Sample": [
{
"SampleNumber": "CCM_K001",
"ManufactureDate": "2021-09-22",
"PreheatingTemperature": 50,
"PreheatingTime": 5
}
]
}


What the receiver does not know from the data is the unit of the measured values. Is the temperature value in °C or K? Is the time value in hours, minutes or seconds?

Is there a recommendation on how to pass on this information? One possibility would be to include the information in the description. So instead of "PreheatingTemperature" then "PreheatingTemperature_Celsius" or instead of "PreheatingTime" then "PreheatingTime_Minutes".

What is the best way to do this?

Many greetings,
Michael

Hi Guenther,

alternatively, you add that information as a separate label in your api.

For example

"SampleNumber": "CCM_K001",
"ManufactureDate": "2021-09-22",
"PreheatingTemperature": {

           "Value" : 50,

           "Unit" : "Celcius",

           "Display" : "50 °C"

},
"PreheatingTime": {

           "Value" : 5,

           "Unit" : "minutes",

           "Display" : "5 min"

}


This has the advantage that you can implement new units in the future without having to change the api structure.


Or you could even take this further :

"SampleNumber": "CCM_K001",
"ManufactureDate": "2021-09-22",
"Measurements": [

          {

           "Name" : "PreheatingTemperature",

           "Value" : 50,

           "Unit" : "Celcius",

           "Display" : "50 °C"

          },
          {

           "Name" : "PreheatingTime",

           "Value" : 5,

           "Unit" : "minutes",

           "Display" : "5 min"

          }

]

This is completely flexible in what measurements you will include, you could for example even put the temperature both in Kelvin and in Celcius as 2 items in your measurements collection.

I think it's important to talk to the consumers of your API to find out in what ways they will use it, and design for ease of use.

Dorine

Hi Michael,

This is the beginner course that amongst others, talks about exposing your own REST API's.

So basically, whatever structure you define as output of your exposed API method, will lead to a given JSON composition.

For your example, you would need structures a bit like this

structure 1 : Measurement

        Name  (text)

        Value   (text or number, depends on whether all your measurements are numeric)

         Unit    (text)

         Display  (text)

structure 2 : Sample

        SampleNumber (text)

        ManufactureDate  (date)

         Measurements (Measurement List)

structure 3 : APIResult

        Success (text)

        ErrorMessage (text)

structure 4 : API<name>Output

        Result (APIResult)

        Samples (Sample List)

And as output of your exposed API action, you just add one API<name>Output.

So you have a list of samples in one response, and each sample has a list of measurements.


Dorine

Hi Guenther,

alternatively, you add that information as a separate label in your api.

For example

"SampleNumber": "CCM_K001",
"ManufactureDate": "2021-09-22",
"PreheatingTemperature": {

           "Value" : 50,

           "Unit" : "Celcius",

           "Display" : "50 °C"

},
"PreheatingTime": {

           "Value" : 5,

           "Unit" : "minutes",

           "Display" : "5 min"

}


This has the advantage that you can implement new units in the future without having to change the api structure.


Or you could even take this further :

"SampleNumber": "CCM_K001",
"ManufactureDate": "2021-09-22",
"Measurements": [

          {

           "Name" : "PreheatingTemperature",

           "Value" : 50,

           "Unit" : "Celcius",

           "Display" : "50 °C"

          },
          {

           "Name" : "PreheatingTime",

           "Value" : 5,

           "Unit" : "minutes",

           "Display" : "5 min"

          }

]

This is completely flexible in what measurements you will include, you could for example even put the temperature both in Kelvin and in Celcius as 2 items in your measurements collection.

I think it's important to talk to the consumers of your API to find out in what ways they will use it, and design for ease of use.

Dorine

Hello Dorine, thank you very much for your answer. I like your second suggestion very much. Are there any tutorials on how to add more labels to an API in Outsystems. This is a very new topic for me.

Thank you very much for your help.
Michael

Hi Michael,

This is the beginner course that amongst others, talks about exposing your own REST API's.

So basically, whatever structure you define as output of your exposed API method, will lead to a given JSON composition.

For your example, you would need structures a bit like this

structure 1 : Measurement

        Name  (text)

        Value   (text or number, depends on whether all your measurements are numeric)

         Unit    (text)

         Display  (text)

structure 2 : Sample

        SampleNumber (text)

        ManufactureDate  (date)

         Measurements (Measurement List)

structure 3 : APIResult

        Success (text)

        ErrorMessage (text)

structure 4 : API<name>Output

        Result (APIResult)

        Samples (Sample List)

And as output of your exposed API action, you just add one API<name>Output.

So you have a list of samples in one response, and each sample has a list of measurements.


Dorine

Community GuidelinesBe kind and respectful, give credit to the original source of content, and search for duplicates before posting.