new API entry: breeding_codes, etc.

[denislepage]

I have added a new API procedure that we should expose to the API.

[prAPI_breeding_codes]

I'll have to have a look at the list of indexed fields to see if any more should be added. I can think of at least a few more (iba, bcr, subnat2, etc.)

[denislepage]

I have also created a few more additional entry points as follow. They should match the various indexed fields provided by the data API (for those that need lookup tables).

/metadata/:

EXEC prAPI_breeding_codes EXEC prAPI_protocol_type EXEC prAPI_protocols EXEC prAPI_bcr EXEC prAPI_subnational2_codes (this one should replace prAPI_subnat2) EXEC prAPI_iba_sites

/data/ EXEC prAPI_utm_squares @statprov = NULL

the latter provides a list of atlas squares that fall within a province. The default is to provide all provinces. To be clear, I would not include this one with the pre-loaded metadata. the square_wkt is the polygon in Well-Known Text OGR format, which could be handy to plot on a map.

(On that note, I also expect to have some WMS layers that we could make available to the R package at a later point for creating maps without having to load the data)

[pmorrill]

The only one of these I can currently see is prAPI_breeding_codes (it seems to work fine).

[pmorrill]

These are all in place, for next deployment. Not all tested though, as I don't seem to have EXEC privilege from my remote account.

[denislepage]

I thought I did this, but I guess not!

Should be visible now. ?

I will likely change a few minor things now to be consistent across the various calls. One of the changes is getting rid of the language parameter and providing both English and French in the same results.

Steffi, the API also offers the ability to filter a few things such as the species codes by authority, but I expect you should just be loading them all at the same time.

I’ll post the list of changes I am making.

[pmorrill]

They seem to all be working from my remote account now. If you deploy bsc-base, Steffi can access them as well.

[denislepage]

List of changes I just made to the API procs. Paul can confirm once they are implemented on the Java side.

[prAPI_bmde_fields]: now support version = NULL (default)

[prAPI_collections]: the language parameter no longer has any impact. Both languages are returned as distinct fields.

[prAPI_projects]: now returns both project_name and project_name_fr. The language parameter is ignored.

[prAPI_projects_metadata]: now returns both project_name and project_name_fr, and tx_access and tx_access_fr. The language parameter is ignored. I will likely add some new fields in this one.

[prAPI_species_authority]: something's wrong with the the data here, but it won't impact the structure or the list of primary keys.

[prAPI_species_codes]: already supports passing NULL as an authority, which provides you the full list of codes for all authorities. That represents 47000 records, but that's it still something lightweight. I don't think paging is necessary.

[prAPI_species_codes_authorities]: a duplicate of prAPI_species_authority. Paul, just let me know which one is used by the API, and I'll delete the other. I don't have a preference.

[prAPI_subnational2_codes]: now supports an optional statprov_code parameter, and fields have changed slightly. Default is to return the full list for the state/provinces in the 3 countries. The R code should simply bring them all in subnat2 table in one shot.

[prAPI_subnat2]: duplicate from the one above. I would probably remove this version, but please confirm when the API no longer refers to it.

[prAPI_utm_squares]: now supports an optional utm_square parameter (returns only 1 square), in addition to the optional statprov_code. The full list is a substantial table of 115,000 records. I am not sure we should allow to download this as a single file, so I may require either a stateprov or utm_square.

I may eventually add a Spanish description to some of the tables. We already have it at least for BCR's and state/provinces.

I think that's it for now!

[steffilazerte]

Is there something about the 2 in subnational2_codes that is important? Or can I drop it for the package data?

[denislepage]

Yes should be kept, it distinguishes from subnational1 (province/states).

[steffilazerte]

Hmm, right now we have stateprov and subnational2

• should these be subnational1 and subnational2?
• Or if we keep statprov, can I switch to subnational?
• Or is this something like an ISO standard? If so, do you have a reference? If we're going to refer to something as '2' in the package, with no '1' I want to make it clear why.

[denislepage]

I understand, but let’s keep them as they are.

State/prov is a lot more useful for people than subnational1.

[steffilazerte]

I agree, and on that same logic, if we're open to renaming, then my suggestion would be to use subnational (without the number), or perhaps even something else entirely (district?)

I can use subnational2 if that's best, I'm just trying to get a sense of what is important vs. just status quo.

[denislepage]

There’s no real consistency among regions how these subnat2 units are named, among provinces, or even within provinces. They are counties in lots of places, but they are divisions, municipalities, districts, etc. are also used.

subnational alone is confusing, unless it refers to provinces and states.

Let’s keep statprov and subnational2.

[steffilazerte]

Sounds good!

[pmorrill]

prAPI_bmde_fields]: now support version = NULL (default)

[prAPI_collections]: the language parameter no longer has any impact. Both languages are returned as distinct fields.

[prAPI_projects]: now returns both project_name and project_name_fr. The language parameter is ignored.

[prAPI_projects_metadata]: now returns both project_name and project_name_fr, and tx_access and tx_access_fr. The language parameter is ignored. I will likely add some new fields in this one.

[prAPI_species_authority]: something's wrong with the the data here, but it won't impact the structure or the list of primary keys.

[prAPI_species_codes]: already supports passing NULL as an authority, which provides you the full list of codes for all authorities. That represents 47000 records, but that's it still something lightweight. I don't think paging is necessary.

[prAPI_species_codes_authorities]: a duplicate of prAPI_species_authority. Paul, just let me know which one is used by the API, and I'll delete the other. I don't have a preference.

[prAPI_subnational2_codes]: now supports an optional statprov_code parameter, and fields have changed slightly. Default is to return the full list for the state/provinces in the 3 countries. The R code should simply bring them all in subnat2 table in one shot.

[prAPI_subnat2]: duplicate from the one above. I would probably remove this version, but please confirm when the API no longer refers to it.

[prAPI_utm_squares]: now supports an optional utm_square parameter (returns only 1 square), in addition to the optional statprov_code. The full list is a substantial table of 115,000 records. I am not sure we should allow to download this as a single file, so I may require either a stateprov or utm_square.

The api uses:

prAPI_species_codes_authorities prAPI_subnational2_codes

You can remove the alternate versions.

Your procs that no longer use '@lang' still seem to require the parameter. I am just handing in an empty string, but maybe you can remove that param entirely, or set a default?

I have now added support for the utmsquare parameter on metadata/utmsquares

[denislepage]

prAPI_species_codes_authorities: I think all fields except the authority code should not have been shown, and they are used for internal reasons. I’ve added a authority_name field, kept the authority field and remove the other ones.

I’m good with removing the alternate versions.

The parameter is currently not required by the procs and can be omitted from the Java code. Once you have confirmed, I will remove it entirely in the procs.

[denislepage]

OK, I have already removed the lang parameters from both Java and the procs, and redeployed the code to sandbox.

[steffilazerte]

Is any of this relevant for me? It doesn't seem like it (all the old API urls work still fine)...

[pmorrill]

This is pretty much all internal tinkering.