For the KSTLookup Shiny App I am providing “taxon criteria trees” via an R-based API hosted “in the cloud.”
The R API was developed using plumber (https://www.rplumber.io/)
The service is run “in the cloud” on a “droplet” [Ubuntu 20.04 / R 4.0.2] (https://www.digitalocean.com/)
HTTP GET provides easy access to the API endpoint: _http://138.68.55.88/kstl_
This initial version of the endpoint requires that code [denoting order in Key logic] and language [EN or SP] be specified, as in this example:
http://138.68.55.88/kstl?code=ABCD&language=SP
Which returns the following JSON result:
{"ABCD":[{"content":"<b><u>A.<\/u><\/b> Suelos que tienen:","chapter":4,"page":42,"key":"Órdenes de Suelo","taxa":"*","crit":"A","clause":1,"logic":"PRIMERA"},{"content":" <b>1.<\/b> Permafrost dentro de 100 cm de la superficie del suelo<i>; o<\/i>","chapter":4,"page":42,"key":"Órdenes de Suelo","taxa":"*","crit":"A","clause":2,"logic":"O"},{"content":" <b>2.<\/b> Materiales gélicos dentro de los 100 cm de la superficie del suelo y permafrost dentro de los 200 cm de la superficie del suelo.","chapter":4,"page":42,"key":"Órdenes de Suelo","taxa":"*","crit":"A","clause":3,"logic":"FIN"},{"content":"Gelisols, pág. 175","chapter":4,"page":42,"key":"Órdenes de Suelo","taxa":"*","crit":"A","clause":4,"logic":"NUEVA"},{"content":"<b><u>AB.<\/u><\/b> Otros Gelisols que tienen uno o más horizontes que muestran crioturbación en forma de límites de horizontes irregulares, quebradizos o distorsionados, como involuciones, acumulación de materia orgánica sobre la parte superior de un permafrost, cuñas de hielo o arena y como fragmentos de roca orientados.","chapter":9,"page":175,"key":"Subórdenes","taxa":"Gelisols","crit":"AB","clause":5,"logic":"FIN"},{"content":"Turbels, pág. 181","chapter":9,"page":175,"key":"Subórdenes","taxa":"Gelisols","crit":"AB","clause":6,"logic":"NUEVA"},{"content":"<b><u>ABC.<\/u><\/b> Otros Turbels que tienen condiciones anhídridas.","chapter":9,"page":181,"key":"Grandes Grupos","taxa":"Turbels","crit":"ABC","clause":7,"logic":"FIN"},{"content":"Anhyturbels, pág. 182","chapter":9,"page":181,"key":"Grandes Grupos","taxa":"Turbels","crit":"ABC","clause":8,"logic":"NUEVA"},{"content":"<b><u>ABCD.<\/u><\/b> Otros Anhyturbels que tienen un horizonte gypsico dentro de los 100 cm de la superficie del suelo mineral.","chapter":9,"page":182,"key":"Subgrupos","taxa":"Anhyturbels","crit":"ABCD","clause":9,"logic":"FIN"},{"content":"<i>Gypsic Anhyturbels<\/i>","chapter":9,"page":182,"key":"Subgrupos","taxa":"Anhyturbels","crit":"ABCD","clause":10,"logic":"ULTIMA"}]}gzip compression and collapsing clauses into “columns” to reduce reuse of identical names could make these results significantly smaller.
For now, the structure with the “clause” as the fundamental taxonomic logical “unit” will be retained but rpresentation will likely be altered as the functionality of the database becomes more robust.
Setting up a plumber API is really simple on your local machine. RStudio provides templates and examples that can be created via File >> New File >> Plumber API….
The gist is that plumber API endpoints are R functions with special markup: #*(similar to Roxygen).
#* Get criteria by taxon code and language
#* @param code Taxon code to query
#* @param language Language database to use
#* @get /kstl
function(code, language) {
# ... API logic goes here ...
}RStudio also provides hosting for plumber API services via RStudio Connect. For my API, I used DigitalOcean [which, like RStudio Connect, is a paid service] that is integrated with R via the plumber and analogsea packages.
For individuals who are semi-experienced with Linux servers the flexibility and low cost of DigitalOcean makes it quite attractive. If all you need is a plumber API, however, RSC may be easier.
Currently DigitalOcean is offering a promotion where if you set up your account they will give you a $100 credit that you can use over a two month period. At the rate that I have been using my credit funds, it is unlikely I will use all of mine in time! I will likely try out some more costly features just to make use of it. Spinning up a Droplet at the lowest tier (what I am using) has a monthly cost of $5 – higher levels of performance and additional features incur greater costs.
This API update comes along with some other improvements to the Soil Taxonomy Shiny Apps and criteria database. See what I have been up to on GitHub: https://github.com/brownag/ncss-standards/tree/master/KST