Serialize Country enum in JSON as ISO country codes
13543
Reporter: bko
Assignee: trobertson
Type: Improvement
Summary: Serialize Country enum in JSON as ISO country codes
Priority: Trivial
Resolution: WontFix
Status: Closed
Created: 2013-08-01 12:19:06.471
Updated: 2013-12-16 17:50:26.63
Resolved: 2013-08-20 12:28:43.302
Description: For a call like this: http://api.gbif.org/node/efb9c00e-f802-45dd-8826-a52ec45b89ff
It shows the country of the node is BENIN. It would be very convenient to also have ISO code (BJ here) when there is a country property. Then a programmer can immediately use the code to query other services without additional 'name-mapping' step.]]>
Author: mdoering@gbif.org
Comment: We should allways serialize the country enum as its ISO code in json, good suggestion!
Created: 2013-08-01 12:25:21.162
Updated: 2013-08-01 12:25:21.162
Author: bko@gbif.org
Created: 2013-08-02 13:59:43.612
Updated: 2013-08-02 13:59:43.612
The same applies to this call:
http://api.gbif.org/node/country
Could this evolve into a country name mapping call, you think?
Author: mdoering@gbif.org
Created: 2013-08-02 16:13:59.689
Updated: 2013-08-02 16:13:59.689
yes, everywhere you see the enumeration names this would then become iso codes.
It is not planned to have the Mendeley mapping included in the java code anywhere right now. We could of course, but I am a bit reluctant as its an additional maintenance burden that could be entirely avoided if we used the iso codes for tagging in the first place
Author: bko@gbif.org
Created: 2013-08-02 16:34:51.654
Updated: 2013-08-02 16:34:51.654
I understand your concern. One reason to support you is, using 2 or 3 digit ISO code is less likely to introduce human typos and less ambiguous, i.e. KR or KP for which Korea. I've noticed some already. But, at the same time I also agree that for most people using Mendeley names are most straight-forward.
I don't think Angel will like to convert all names to ISO code for more than 1400 documents.
Looks like I'll have to do it in Drupal in short term.
I still however suggest the mendeley country name should be served from our official API, so any party can use our API to do different grouping of mendeley articles according to the country tags.
Author: mdoering@gbif.org
Comment: best to create a new issue for this then and leave this one for the Country enum serialization
Created: 2013-08-02 17:06:32.428
Updated: 2013-08-02 17:06:32.428
Author: bko@gbif.org
Comment: Agree - I'll see if the mendeley discussion materialises and set up a new issue if necessary.
Created: 2013-08-02 17:11:57.711
Updated: 2013-08-02 17:11:57.711
Author: trobertson@gbif.org
Created: 2013-08-12 13:28:04.557
Updated: 2013-08-12 13:28:04.557
Fixed with
https://code.google.com/p/gbif-common-resources/source/detail?r=1624
Visible on Staging now:
http://staging.gbif.org:8080/registry2-ws/node/efb9c00e-f802-45dd-8826-a52ec45b89ff
Author: bko@gbif.org
Created: 2013-08-12 17:16:51.696
Updated: 2013-08-12 17:22:35.843
Thanks, Tim! It was fast. Perhaps it was not made clear. I would propose to have the iso code and country enum at the same time. For example, with /node/country, we could have:
[
{
"enumName": "BENIN", // As it was.
"iso2": "BJ",
}
{ ... }
]
And on this call, the property name should be consistent:
"country":"BJ" => "iso2":"BJ"
and we still keep the:
"enumName": "BENIN"
This way, the user of these call can easily 'query' and get the whether they need iso code or enum name to continue.
Could you please revise it?
Burke
Author: bko@gbif.org
Comment: Please see the last comment.
Created: 2013-08-12 17:17:38.878
Updated: 2013-08-12 17:17:38.878
Author: mdoering@gbif.org
Comment: Why would anyone want to know the java enum name? If you use the java clients the iso codes become the real enum, so there is no change. It is just the json serialization that has changed. I think its excellent as it is now
Created: 2013-08-12 18:50:32.672
Updated: 2013-08-12 18:50:32.672
Author: bko@gbif.org
Created: 2013-08-12 19:11:04.212
Updated: 2013-08-12 19:11:04.212
I see the java enum name as the 'machine_name', which I can use without worrying if there is any space, comma, etc. This is very useful from a Drupal developer's perspective, because in Drupal, usually a field or variable reference has a format like that, and when things are displayed, it uses a verbatim property for the display purpose. I.e. If I have and array like this:
array(
'country' => t('Costa Rica'),
'enumName' => 'costa_rica',
'iso2' => 'CR',
);
The string wrapped by t() can be immediately available for internationalisation, while a developer can always use costa_rica without worrying how 'Costa Rica' is going to be presented according to the language setting.
Having iso2 and enumName together is also useful for a developer to know the country immediately. This saves some looking-up time and is useful when debugging or sorting issues out.
Author: trobertson@gbif.org
Created: 2013-08-17 08:34:52.428
Updated: 2013-08-17 10:27:13.481
I don't believe this is wise - especially to use the Java enum name (e.g. UNITED_STATES which is not something you'd want to show a user on a page - you'd want "United State of America" or similar). The iso code is a well known unique identifier for the entity. If someone needs a label for that, they can easily map it using a properties file with internationalization to display in different languages for example, or bootstrap their application using http://staging.gbif.org:8080/registry2-ws/enumeration/country if needed.
currently we have the likes of:
{code}
{
key: 1234-1234-1234-1234,
country: "US"
}
{code}
I think you are requesting:
{code}
{
key: 1234-1234-1234-1234,
countryIso: US,
countryLabel: United States
}
{code}
This one is actually difficult the way the Java app is put together, since it affects every model that the object is used in. Think for example what you would do with a model object that might have:
{code}
public class Dataset {
UUID key;
Country[] coverages;
Country publishingCountry;
Country hostingCountry;
}
{code}
It would really need to be along the lines of:
{code}
{
"key": 1234-1234-1234-1234,
publishingCountry: {
iso: US,
title: United States
}
}
{code}
Which is easy to implement but produces verbose JSON.
I propose to close this as not fixed, and people wishing to display labels for countries do so as they see fit - the ISO 3166 alpha2 is a well known standard and using the codes from there is fairly common practice.
Author: bko@gbif.org
Created: 2013-08-17 11:05:27.756
Updated: 2013-08-17 11:05:27.756
Thank you for taking time explaining, Tim. You understand my request perfectly and I can see your point better now. I like the last format you propose and I don't mind it's verbose. From the perspective of an API user, to allow to have those values in one call can save a few lines of code finding another source and looking for a match. Client app will be simpler and cleaner because of this verboseness.
I still recommend we implement it as I see the benefit for users, especially if it's easy to. But your call, please, given our tight resource before GB.
Thanks again!
Author: bko@gbif.org
Created: 2013-08-27 14:58:17.305
Updated: 2013-08-27 14:58:17.305
I think I still document here. Now I hit the situation, but perhaps temporary. I first call:
/node/efb9c00e-f802-45dd-8826-a52ec45b89ff
where I have country as BJ, and I want to call
/occurrence/count?hostCountry=BENIN&georeferenced=true
where I can only use BENIN, which is not available from the first call.
Therefore between these calls, I need to find the enumName of BJ by calling and parsing
http://apidev.gbif.org/enumeration/country
I think if we want to emit only ISO code in the JSON result, it'll be convenient for API users if we also adopt ISO code for country facet in all of our API calls.
Author: mdoering@gbif.org
Created: 2013-08-27 15:38:53.459
Updated: 2013-08-27 15:38:53.459
Yes Burke, see the 2 open related issues REG-396 and MET-29.
I agree these need to be fixed soon!
Author: bko@gbif.org
Comment: Many thanks, Markus! I have just started watching those two issues so I can adopt the change on my NPT code.
Created: 2013-08-27 15:42:47.748
Updated: 2013-08-27 15:42:47.748