Sarebbe utile avere indicazioni sulla lingua da utilizzare per il naming delle risorse e payload delle API.
Nel caso in cui il naming fosse inglese, sarebbe opportuno avere il dizionario di riferimento.
Un possibile utilizzo potrebbe essere lo IATE
(http://iate.europa.eu/switchLang.do?success=mainPage&lang=en).
Sempre in questo paragrafo occorre disambiguare alcuni aspetti poiché nei documenti INSPIRE citati come riferimento per i Core Vocabularies i nomi sono in camelCase (countryOfBirth), il che contraddice la prassi snake_case delle API riportata in questo paragrafo, nel quale è scritto:
“… Il campo Query dovrebbe:
• essere in snake_case minuscolo;
• non essere in camelCase;…”
Nella nota 74 poi si specifica di “…usare parole minuscole separate da trattino «-«;…” ma nello snake_case non si usa il trattino.
Buongiorno Gabriella,
e grazie per il suggerimento! Ne terremo conto.
Chiarisco il contenuto delle Linee Guida:
- dove esiste uno standard specifico, eg. INSPIRE, va’ seguito lo standard;
- dove non esiste uno standard, deve preferirsi (dovrebbe, non deve) lo snake case;
La nota 74 fa’ riferimento al path delle API, e non ai nomi delle variabili e/o ai parametri.
Esempio:
https://api.example.com/documenti/dichiarazioni-redditi?codice_fiscale=AAABBB77T05A512W
Questo permette di individuare chiaramente quello che è un URL path da quello che invee è un parametro.
Se hai altre domande fai sapere!
Buongiorno Roberto,
rispetto alla prima parte della domanda posta da Gabriella relativa alla lingua da utilizzare per il naming ed al corrispondente dizionario di riferimento, intendete dare indicazioni in merito in uno dei prossimi documenti?
Grazie.
Ciao Guido,
per il naming delle risorse, le linee guida indicano qui e qui il punto di partenza:
- gli standard di riferimento del dominio applicativo (sanitario, geografico, …)
- le linee guida sul patrimonio pubblico http://lg-patrimonio-pubblico.readthedocs.io/it/latest/
- i vocabolari controllati https://github.com/italia/daf-ontologie-vocabolari-controllati
Nei casi non coperti da indicazioni specifiche quindi:
- non c’è l’obbligo di scrivere in inglese.
- qualora si optasse per l’inglese, è stata ripresa la convenzione di IEEE di usare la dizione statunitense
L’utilizzo di un dizionario specifico - eg. quello segnalato da Gabriella - è un’idea interessante ma non in roadmap.
Se volete proporre emendamenti specifici alle Linee Guida - eg. per renderle più chiare anche alla luce di questi scambi - potete farlo tramite github.
Fatemi sapere se avete bisogno di qualche indicazione in più,
e grazie ancora per i commenti,
R: