Problematic API specification
Closed this issue · 4 comments
The API doc specifies language support for logos and display names.
The problem is that it is defined as a dictionary keyed by a locale identifier. There is no order defined. Yes, there is an implicit order specified on the server end in the order that the items are rendered.
To work around this, either there needs to be an additional key containing a value to be used for fallback. Another option would be to structure the data as:
"display_name": [
{"en-US": "Demo VPN Provider"},
{"nl-NL": "Demo VPN-aanbieder"}
]
Why is this important? Most JSON parsing libraries parse a JSON dictionary into a hash map, dictionary or similar keyed data structure. These data structures are usually not ordered, so at that moment the ordering from the server is not preserved.
On iOS I will look for a matching keys by calling Bundle.preferredLocalizations(from:availableKeys) this will follow the semantics used for localization on iOS. But if no match is found I need to be able to have a deterministic and predictable way to "take a default".
A decent default would be to "take the first". But an orderless data structure such as a dictionary does not support the concept of a first item.
I tried to solve this by defining it out of scope of the API documentation, I guess that bit me now! ;-)
Applications MUST check if the value of display_name and logo is a simple string, or an object. In
case of an object, the language best matching the application language SHOULD be chosen. If that
language is not available, the application SHOULD fallback to en-US. If en-US is not available, it is up
to the application to pick one it deems best.
So taking the first, or one at random will not work? Maybe I should specify that en-US MUST always there if there are multiple entries? That may be the easiest?
That'll work. :)
It doesn't really make sense to make it required. For eduVPN we'll always have en-US as fallback, so it is up to the discovery file provider to make sure it is there. If the chosen language, and en-US is not there, the behaviour is unspecified. You could show an error message, or just pick one at random.