Context
In the development of a product, I am faced with managing various enumerated values to categorize different data types. This is particularly relevant in C programming for a microcontroller environment:
typedef enum
{
Temperature = 100,
InputVoltage = 200,
AverageVoltage = 201,
Current = 300,
} ReadingType_t;
This approach enables us to handle "reading" data in a generic manner, as illustrated below:
typedef struct
{
ReadingType_t type;
sint32_t value;
} Reading_t;
Reading_t readings[5];
readings[0].type = Temperature;
readings[0].value = 25; // in degrees C
readings[1].type = InputVoltage;
readings[1].value = 4321; // in milliVolts
Challenge
My current task involves defining a JSON-based API for displaying information structured like this. Several potential formats are being considered:
readings = [
{
"type": "Temperature",
"value": 25
},
{
"type": "InputVoltage",
"value": 4321,
}
]
or
readings = [
{
"type": 100,
"value": 25
},
{
"type": 200,
"value": 4321,
}
]
or
readings = [
{
"type": {
"code": 100,
"name": "Temperature"
},
"value": 25
},
{
"type": {
"code": 200,
"name": "InputVoltage"
},
"value": 4321,
}
]
Assumptions
It is assumed that the API will produce JSON output.
The API is expected to be utilized by a JavaScript client application and/or directly accessed for debugging purposes.
Key Questions
My inquiries revolve around the following:
- Should both the enumeration "code" and its corresponding "name" be included? Is there a standard convention for this dilemma?
- If including the "name," should it follow a conventional language format? For instance, should it be "InputVoltage" or "Input Voltage"?
- How can support for Internationalization be balanced with user-friendliness? For example:
- Emphasizing the numeric "code" would eliminate ambiguity regarding the data type, but require a lookup table for converting to human-readable strings (potentially necessitating separate tables for internationalization).
- Sending the "name" in natural language would delegate internationalization responsibilities to the API (which may be acceptable), but hinder logical operations based on the value (as the "name" varies based on language while the code remains constant).