Documentare il rilascio con API: mi consigliate qualche esempio?

[Alberto]

Ciao, sono impegnato in un progetto di ricerca europeo che aderisce all'Open Data Pilot della Commissione. Alla fine abbiamo deciso che ci viene bene rilasciare i dati via API: ci saranno degli indirizzi web che ritornano ciascuno un file JSON. È poi un'API per modo di dire, non riesco a immaginare un uso che non sia di prendersi tutto il JSON e scaricarlo in locale per poi pasticciarci a fini di ricerca. Usiamo le API di Drupal solo perché ci risparmiamo la fatica di montare e aggiornare una struttura a parte. 

La domanda è: esistono standard per la documentazione in questi casi? Ai tempi, qualcuno (credo Matteo B) mi aveva aperto un mondo con la standard Data Package, che è strutturato, sostenuto da una comunità d'uso (OKFN) e abbastanza semplice. In questo caso non posso usarlo, perché il file datapackage.json con i metadati dovrebbe stare nella stessa directory del file con i dati... ma qui non c'è nessuna directory, e il file di dati viene generato automaticamente. Idee?

[andy]

2016-05-23 19:14 GMT+02:00 Alberto <alberto...@gmail.com>:

In questo caso non posso usarlo, perché il file datapackage.json con i metadati dovrebbe stare nella stessa directory del file con i dat

Non l'ho mai usato, ma l'avevo messo da parte: https://apiblueprint.org

Il datapackage file potrebbe essere generato live e fare riferimento a una risorsa via URL. Ma non so se ho capito

--

 Andrea Borruso
website: http://blog.spaziogis.it
38° 7' 48" N, 13° 21' 9" E, EPSG:4326

--

"cercare e saper riconoscere chi e cosa,
 in mezzo all’inferno, non è inferno, 
e farlo durare, e dargli spazio"

Italo Calvino

[Paolo Riva]

Per quello che ne so esistono differenti standard a seconda della metodologia con cui vuoi rilasciare quelle api?

Es: sono delle API REST? Mi spiego meglio: l'URL vuole essere "parlante" (http://miourl/risorsa/ => http://miosito/configurazione/) o è molto piu semplice (URL differenti richiamano risorse differenti senza una particolare logica).

Noi sul progetto di Sports Open Data abbiamo usato le API REST e ci siamo attenuti a queste best practicies:

http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

Tieni conto che la RESTFULNESS è un argomento molto apprezzato (specie perchè considerato ordinato e facile da gestire).

Non esiste un vero e proprio "generatore" in questo senso: molto dipende dalla tipologia di informazioni che fornisci dalle quali puoi generare le risorse da esporre che ti serve fornire.

Per qualsiasi info fammi sapere.

Ciao Paolo.

--
Hai ricevuto questo messaggio perché sei iscritto al gruppo "Spaghetti Open Data" di Google Gruppi.
Per annullare l'iscrizione a questo gruppo e non ricevere più le sue email, invia un'email a spaghettiopend...@googlegroups.com.
Visita questo gruppo all'indirizzo https://groups.google.com/group/spaghettiopendata.
Per altre opzioni visita https://groups.google.com/d/optout.

--

Paolo Riva

Soccer Talent Scout

Website: http://ilpaoloriva.wordpress.com

Tel: +39 327 2837646

Skype: pavlov982

Twitter: @ilpaoloriva

[Paolo Mainardi]

Consiglio questo: http://apiary.com o meglio http://swagger.io

Ciao, sono impegnato in un progetto di ricerca europeo che aderisce all'Open Data Pilot della Commissione. Alla fine abbiamo deciso che ci viene bene rilasciare i dati via API: ci saranno degli indirizzi web che ritornano ciascuno un file JSON. È poi un'API per modo di dire, non riesco a immaginare un uso che non sia di prendersi tutto il JSON e scaricarlo in locale per poi pasticciarci a fini di ricerca. Usiamo le API di Drupal solo perché ci risparmiamo la fatica di montare e aggiornare una struttura a parte. 

La domanda è: esistono standard per la documentazione in questi casi? Ai tempi, qualcuno (credo Matteo B) mi aveva aperto un mondo con la standard Data Package, che è strutturato, sostenuto da una comunità d'uso (OKFN) e abbastanza semplice. In questo caso non posso usarlo, perché il file datapackage.json con i metadati dovrebbe stare nella stessa directory del file con i dati... ma qui non c'è nessuna directory, e il file di dati viene generato automaticamente. Idee?

--

[Alberto]

Ok, questo è il tipico "momento newbie". Non ci capiamo, il che significa che probabilmente ho usato la parola API a sproposito. Di solito nei "momenti newbie" io finisco per imparare un sacco di roba. 

Quindi, chiedendo scusa in anticipo a Andrea, Paolo e Paolo, provo a spiegarmi meglio. Faccio qualche riferimento a Drupal, che almeno a Paolo M non dovrebbe dispiacere.

Drupal ha un modulo core che si chiama Views. Serve per pescare roba dal database e metterla sulla pagina. Nel tempo, Views ha acquisito una funzionalità che, invece, pesca roba dal database e te la serve in formato JSON. Il JSON ha una propria url, tipo http://miosito.org/utenti.json

Questa url si può anche aprire dal browser. Se lo fai, trovi una roba tipo:

{"users" : [
         {
         "user" : {
                 "name" : "Alberto","account_created":"2013-03-05"
                 }
         },
         {
         "user" : {
                 "name" : "Paolo","account_created":"2013-03-01"
                }
         }
         ...
}

Io questa roba la chiamo API perché (1) il JSON si popola dinamicamente quando lo chiami e (2) in teoria puoi manipolare delle risorse direttamente prendendotele dal server. Per esempio, in Python:

import urllib2
import simplejson

url = 'https://miosito.org/utenti.json'
response = urllib2.urlopen(url)
data = simplejson.load(response)

for user in data['users']:
    print data['users'][user]['name']

>>>
'Alberto'
'Paolo'

Ma forse sbaglio. Se non si chiama API, come si chiama?

Per cui la documentazione dovrebbe essere una roba che:

1. Spiega la struttura del JSON, in modo che uno si possa costruire la query come gli pare. 
2. Rispetta un qualche tipo di schema già inventato in modo da non costringere il povero riutilizzatore a entrare in una logica che magari è solo mia. 

Andrea: in effetti l'idea di mettere un datapackage.json da qualche parte mi è venuta. Ma ho lo scrupolo: l'idea di "package" è pensata per i dump. Tu hai una directory, ci metti i dati e i metadati, questi ultimi nel file datapackage.json. Io la directory non ce l'ho. Però fooorse potrei simularla fissando il path in questo modo: 

• https://miosito.org/utenti/data.json contiene i dati
  
• https://miosito.org/utenti/datapackage.json contiene i metadati. 
  

Un problema più serio è che, per quanto mi ricordo, Data Package non consente di documentare la struttura del dizionario JSON. Cioè, non solo spiegare che "name" è il nome utente (e non il nome di battesimo), ma anche che "name" è una chiave di un dizionario che a sua volta è un valore di un dizionario che si chiama "user", che a sua volta è un elemento di una lista... eccetera. Chiaramente, questo qui è importante.

[Paolo Riva]

Ciao Alberto,

tendenzialmente quando si parla di API si intende una modalità di interfacciarsi da parte di un utente (o di una macchina) verso un'applicazione per ottenerne informazioni. Di conseguenza possiamo dire che, seppur nel caso specifico di una singola chiamata, questa risorsa fornita è, di fatto, una API.

La comodità di questo tipo di infrastruttura, a differenza del classico package che ti scarichi e via, è che la risorsa è interrogabile: quindi puoi prefiltrare i contenuti e quant'altro il che la rende molto appetibile specie se te la vuoi lavorare successivamente.

Personalmente non credo esista un vero e proprio standard di response: questo perchè il json è un contenuto fortemente tipizzabile, di conseguenza non avrebbe senso inserirlo in una struttura statica non personalizzabile. Da li preferibile pensare a delle "best practices" che ti aiutano a costruire una struttura che sia facilmente comprensibile da chi la legge.

Sicuramente per capire come costruire la tua response ti rimando al documento che già ti avevo segnalato: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

Per quanto riguarda la documentazione sicuramente la scelta di utilizzare swagger è molto comoda, alternative valide possono essere anche mashape (https://www.mashape.com/) e ApiGee (https://apigee.com/). Entrambi sono free (permettono di abilitare delle funzionalità a pagamento ma con la funzionalità free funzionano alla perfezione) e con la costruzione di un piccolo client interno alla loro infrastruttura (ci sono i wizard) ti permettono di creare delle documentazioni facili da comprendere per chi le utilizza oltre a permetterti di avere anche dei client embeddabili in pagine web.

Premetto che, personalmente, preferisco di gran lunga mashape: ti giro comunque un paio di esempi su come abbiamo impostato le attività di Sports Open Data su questi applicativi:

http://sportsopendata.net/api-console/ (una console con le informazioni delle nostre api fatta con ApiGee)

https://market.mashape.com/sportsop/soccer-sports-open-data (La nostra pagina su mashape)

Per qualsiasi info, o se sono finito ancora fuori argomento, fammi sapere ;)

Ciao Paolo.

--

Hai ricevuto questo messaggio perché sei iscritto al gruppo "Spaghetti Open Data" di Google Gruppi.
Per annullare l'iscrizione a questo gruppo e non ricevere più le sue email, invia un'email a spaghettiopend...@googlegroups.com.
Visita questo gruppo all'indirizzo https://groups.google.com/group/spaghettiopendata.
Per altre opzioni visita https://groups.google.com/d/optout.

[Maurizio Napolitano]

2016-05-23 23:37 GMT+02:00 Alberto <alberto...@gmail.com>:
> Ok, questo è il tipico "momento newbie". Non ci capiamo, il che significa
> che probabilmente ho usato la parola API a sproposito.

Secondo me non hai usato la parola a sproposito, hai solo tracciato
una tua idea basata sulla tua esperienza.
API = Application Programming Interface

pertanto si tratta di qualsiasi libreria (su come la raggiungi poi è
un altro discorso) a cui ti colleghi
Ti riporto l'esempio usato su wikipedia perchè è molto grazioso
----
Le API sono essenziali per il computer come gli standard elettrici lo
sono per una casa. Chiunque può inserire la spina del tostapane nella
presa a muro della sua casa o dal vicino perché entrambe le case sono
conformi ad uno standard. Se non ci fosse una interfaccia standard,
occorrerebbe avere una centrale elettrica per fare un toast. Niente
vieta che esistano più tipi di interfacce diverse, per esempio un
tostapane europeo non può funzionare negli Stati Uniti senza un
trasformatore; in modo simile, un programma scritto per Microsoft
Windows non può essere eseguito direttamente su un sistema UNIX senza
un API adapter come WINE.
---
Come puoi capire le API possono essere sul tuo computer o su uno remoto.
Quando poi sono su http allora si parla di webservice.
Ci sono werbservice molto strutturati come SOAP ed altri meno ma che
risultanto essere più semplice da usare come REST.
Come interscambio dei messaggi puoi spedire xml o txt o json o pbf o
ilformatodispaghettiopendata ecc...

Il mio consiglio è di seguire i suggerimenti di Paolo Riva.

[Alessio Dragoni]

Alberto,
il best in class, secondo molti analisti indipendenti e' http://swagger.io
TI consiglio anche di dare un'occhio a https://openapis.org/

un saluto,
Alessio

[Nicola Ghirardi]

Confermo Paolo, https://help.apiary.io/swagger/

[Matteo Brunati]

In aggiunta a quanto detto, esiste un bel tool per creare una documentazione leggibile di API: (l'approccio REST è fondamentale eh)

https://github.com/tripit/slate

Poi anche queste best practices sono molto ben fatte: (Data on the Web, W3C)

• https://www.w3.org/TR/dwbp/#accessAPIs (la 23, 24 e 25 nel tuo caso soprattutto)
  

matt

[Paolo Riva]

+1 Matteo

Bella la pagina sulle best practices.

Ciao Paolo.

--

Hai ricevuto questo messaggio perché sei iscritto al gruppo "Spaghetti Open Data" di Google Gruppi.
Per annullare l'iscrizione a questo gruppo e non ricevere più le sue email, invia un'email a spaghettiopend...@googlegroups.com.
Visita questo gruppo all'indirizzo https://groups.google.com/group/spaghettiopendata.
Per altre opzioni visita https://groups.google.com/d/optout.

[Alberto]

Ragazzi, grazie come sempre, siete una miniera.

Mi piace molto il modo di ordinare la cosa di Mashape! Però mi sfugge una cosa. Tu tieni i tuoi dati sul tuo server, ma la documentazione delle API sul sito di Mashape? Che senso ha? E se Mashape chiude, o cambia i TOS? Devi stare attento a DUE servizi su due macchine diverse, con due fornitori diversi. Questo non rende il processo più fragile? 

FYI, la Commissione Europea finanzia una sua infrastruttura per pubblicare open data di ricerca: si chiama Zenodo, gestito da CERN. Il CERN probabilmente manterrà quella roba online fino a che il sole non sarà diventato una gigante rossa, quindi il problema dell'affidabilità è risolto. Ma mi sembra che siano orientati a collezionare data dump piuttosto che a documentare API.  Non capisco benissimo la loro documentazione, per esempio qui: https://www.openaire.eu/repmanager-guide . Mi pare di capire che Zenodo sia nato come sviluppo di OpenAire, l'iniziativa per l'open access sulla ricerca finanziata europea. Andrea Zanni, ne sai qualcosa? 

Ho inviato una domanda ai gestori di Zenodo, vediamo se impariamo qualcosa. 

[Alberto]

Seeh. #fail 

Thank you for your message. Note, due to overwhelming interest, we are currently also refurbishing our infrastructure. As a result the response times to support requests are longer than usual, so please bear with us until the new infrastructure is scheduled to be put in place. Thank you for your understanding and we hope you'll find the Zenodo improvements well worth waiting for!

[Paolo Riva]

Ciao Alberto,

ti rispondo in merito al discorso di mashape.

Devi tenere conto che mashape è un collettore di api: lui non ha niente e/o non gestisce niente.

Semplicemente tu configuri quella che loro chiamano applicazione (che per te non è altro che una configurazione) all'interno della quale non fai nient'altro che inserire tutte le url che rendi disponibili nelle tue API.

Non c'è quindi una doppia manutenzione, semplicemente hai le tue api replicate automaticamente anche su mashape: chiaro che se cambi le specifiche di filtering dovrai cambiarle anche li. La comodità di Mashape, ovviamente, sta nel fatto della community: prima di tutto hai una community che testa le tue API e ti da opinioni in merito (a noi addirittura aprono delle issues nel caso in cui ci sono doppioni o dati discordanti) altri semplicemente richieste su dati aggiuntivi.

Personalmente preferisco una scelta "alla Mashape" perchè danno visibilità di un lavoro a dei tecnici (quello è il target di Mashape) di conseguenza puoi avere un palcoscenico molto ampio al quale puoi dare visibilità (e perchè no, nuovi stimoli) al tuo progetto.

Sicuro hai la scomodità che non hai la documentazione delle tue API sul tuo sito (ma le hai su mashape): personalmente non la ritengo una grande problematica, anche perchè da come descrivi il progetto la parte interessante non è tanto il numero di api, quanto il cosa possono restituire con filtri differenti (che su mashape configuri in pochi passi).

Spero che possa esserti utile come spiegazione se hai bisogno altre info chiedi pure.

Ciao Paolo.

PS: Interessante Zenodo, ma sono d'accordo con te sul fatto che cerchino piu dei data dump che documentare API.

2016-05-25 12:12 GMT+02:00 Alberto <alberto...@gmail.com>:

Seeh. #fail 

Thank you for your message. Note, due to overwhelming interest, we are currently also refurbishing our infrastructure. As a result the response times to support requests are longer than usual, so please bear with us until the new infrastructure is scheduled to be put in place. Thank you for your understanding and we hope you'll find the Zenodo improvements well worth waiting for!

--

Hai ricevuto questo messaggio perché sei iscritto al gruppo "Spaghetti Open Data" di Google Gruppi.
Per annullare l'iscrizione a questo gruppo e non ricevere più le sue email, invia un'email a spaghettiopend...@googlegroups.com.
Visita questo gruppo all'indirizzo https://groups.google.com/group/spaghettiopendata.
Per altre opzioni visita https://groups.google.com/d/optout.

[Alberto]

Ciao a tutti, giusto per restituire un'informazione interessante a tutti quelli che hanno contribuito (e grazie ancora!): ho finalmente ricevuto una risposta da quelli di Zenodo. In pratica: 

• Zenodo è pensato come repository di dati statici. Vantaggio: struttura robusta (la stessa che stiva i dati del Large Hadron Collider, per dire), e aspettativa che i dati resteranno online per moolto tempo. 
• Per dataset in evoluzione, non funziona molto. Ti offrono di mantenere uno snapshot. 
• La documentazione delle API non è un punto forte di Zenodo. "we haven't found sounds that satisfies our need fully. Usually, auto-generated documentation from the code is not very developer friendly but can be display without extra servers, where as developer friendly documentation is usually best hosted by external tools."

Conclusione provvisoria:

• dati "live" hostati in casa. 
• documentazione API su Mashape, con ridondanza (un wiki su Edgeryders)
• forse uno snapshot su Zenodo alla fine del progetto

[Paolo Riva]

Secondo me lo snapshot è da considerare assolutamente.

--

Hai ricevuto questo messaggio perché sei iscritto al gruppo "Spaghetti Open Data" di Google Gruppi.
Per annullare l'iscrizione a questo gruppo e non ricevere più le sue email, invia un'email a spaghettiopend...@googlegroups.com.
Visita questo gruppo all'indirizzo https://groups.google.com/group/spaghettiopendata.
Per altre opzioni visita https://groups.google.com/d/optout.

[Alfredo Serafini]

aggiungo in colpevole ritardo (scusatemi, sono sovraccarico e in ritardo di decine di post) una nota su swagger, che è il mio preferito. :-)

Occhio che può essere usato sia direttamente nel backend (in Java ad esempio puoi integrarlo con le annotazioni dei tuoi controllers, ma se non erro esistono implmentazioni alternative python e php), il che è utile se hai decine di api che possono magari anche cambiare e diventa faticoso farne manutenzione.

Altrimenti puoi semplicemente editare il prodotto finito (ad esempio da qui: http://editor.swagger.io/): cioè dei config json, eventualmente personalizzare html/js se ti serve (di solito anche no) e pubblicare sul tuo webserver apache o quello che è. Tanto per capirci sta alle API come datapackage sta ai metadati :-)

[Alberto]

Torno su questo thread, perché adesso provo a lavorarci davvero. 

Vediamo se ho capito.

Documentare le API vuol dire fare due cose:

1. Una pagina con esempi di richieste e risposte a quelle richieste. Il W3C lo fa così.
2. Una pagina dove i metadati sono descritti in formato human-readable. Il W3C lo fa così – molto diverso dall'impostazione di DataPackage per i dataset statici. Ma forse posso usare anche il formato Data Package, no? Le informazioni sono le stesse, ed è abbastanza human-readable.

Giusto?

Riguardo a 1: io so' gnorante, ma le richieste non dipendono dal linguaggio? Quindi, invece di mettere "get" e basta, non avrebbe più senso fare un esempio di script? Ma poi bisogna fare esempi in vari linguaggi? Io una cosa così la capirei:

>>> import requests
>>> response = requests.get('http://example.com/mydata')
>>> mystuff = response.json()
>>> print mystuff

{'nodes':[
       {  
         'node':{
                'key1':'value1',
                'key2': 'value2',
                },
       ...
       ]
     }


 

Ultima domanda. Su swagger tutte le richieste hanno il codice 200. In effetti:

>>> import requests
>>> response = requests.get('http://example.com/mydata')
>>> print response
<Response [200]>

Cosa vuol dire? Devo usarlo?

[Irene Celino]

ciao alberto, una veloce risposta.

tutte le web api "parlano" lo stesso linguaggio ovvero http, indipendentemente dal linguaggio di programmazione che viene usato per implementarne la business logic (php, java, python, ...).

tutte i metodi delle api in http appartengono a pochi tipi primitivi: get (per richiedere dei dati, 90+% dei casi, incluso il tuo esempio), post (per inviare dati), delete (per cancellare), put (per modificare).

ad ogni richiesta http corrisponde una risposta http che è caratterizzata anche da uno status code: 200 (e famiglia di codici 20x) vuol dire che è andato tutto bene, i codici delle famiglie 400 e 500 indicano un errore (il più noto è il 404 "not found"). nel tuo esempio sopra, se la get va a buon fine e restituisce i dati richiesti, lo status code della risposta è 200.

quando documenti un'api quindi in genere per ogni metodo devi dire 1. che tipo primitivo usi (get/post/...), 2. in caso di successo, ovvero status 200, com'è fatta la risposta (è in json, è in xml, ha una certa struttura, ecc.), 3. quali casi di errore prevedi (con rispettivi status code). se non prevedi nessuna particolare gestione degli errori (ad es. se la get non va a buon fine restituisce un json vuoto) puoi evitare di specificare i casi di errore (anche se ovviamente non sarebbe buona pratica...).

secondo me, per i "neofiti" delle api, swagger non è la cosa più user-friendly (anche se molto potente, lo standard quasi de facto, anche in corso di standardizzazione sotto altro nome); se vuoi una cosa più user-friendly, io ho usato un altro linguaggio di descrizione chiamato api blueprint che è quello usato in tool come apiary: https://apiary.io/. poi se serve esistono vari servizi web di "traduzione" da un linguaggio di descrizione all'altro...

hth,

irene

--

Hai ricevuto questo messaggio perché sei iscritto al gruppo "Spaghetti Open Data" di Google Gruppi.

Per annullare l'iscrizione a questo gruppo e non ricevere più le sue email, invia un'email a spaghettiopendata+unsubscribe@googlegroups.com.

Visita questo gruppo all'indirizzo https://groups.google.com/group/spaghettiopendata.
Per altre opzioni visita https://groups.google.com/d/optout.

--

http://about.me/iricelino/

    " If you understand what you're doing,
           you're not learning anything. "

[Alfredo Serafini]

swagger (open API) è senz'altro il metodo da guardare per le descrizioni per esseri umani, è molto più curato nella UX e nella espressività di apiary in realtà.

Se vuoi invece machine-to-machine guarda su hydra ;-)

Per annullare l'iscrizione a questo argomento, visita https://groups.google.com/d/topic/spaghettiopendata/2V8BwPJWUVo/unsubscribe.
Per annullare l'iscrizione a questo gruppo e a tutti i suoi argomenti, invia un'email a spaghettiopendata+unsubscribe@googlegroups.com.

[Alberto]

Irene! Grazie davvero. Al prossimo raduno ti offro la colazione. Adesso ho capito veramente. Ultima domanda, che è più di good practice che altro: come mettere insieme diverse API che fanno riferimento allo stesso progetto?

Nel mio caso, ne ho cinque: una che tira giù i post, una che tira giù i commenti etc.

Posso: 

1. Documentarle tutte nello stesso documento. 
2. Creare cinque documenti diversi che stanno sullo stesso repo GitHub.

L'unico metodo è GET in tutti i casi. Cosa mi consigliate?

A.

On Friday, November 4, 2016 at 6:09:38 PM UTC+1, Irene Celino (iricelino) wrote:

ciao alberto, una veloce risposta.

tutte le web api "parlano" lo stesso linguaggio ovvero http, indipendentemente dal linguaggio di programmazione che viene usato per implementarne la business logic (php, java, python, ...).

tutte i metodi delle api in http appartengono a pochi tipi primitivi: get (per richiedere dei dati, 90+% dei casi, incluso il tuo esempio), post (per inviare dati), delete (per cancellare), put (per modificare).

ad ogni richiesta http corrisponde una risposta http che è caratterizzata anche da uno status code: 200 (e famiglia di codici 20x) vuol dire che è andato tutto bene, i codici delle famiglie 400 e 500 indicano un errore (il più noto è il 404 "not found"). nel tuo esempio sopra, se la get va a buon fine e restituisce i dati richiesti, lo status code della risposta è 200.

quando documenti un'api quindi in genere per ogni metodo devi dire 1. che tipo primitivo usi (get/post/...), 2. in caso di successo, ovvero status 200, com'è fatta la risposta (è in json, è in xml, ha una certa struttura, ecc.), 3. quali casi di errore prevedi (con rispettivi status code). se non prevedi nessuna particolare gestione degli errori (ad es. se la get non va a buon fine restituisce un json vuoto) puoi evitare di specificare i casi di errore (anche se ovviamente non sarebbe buona pratica...).

secondo me, per i "neofiti" delle api, swagger non è la cosa più user-friendly (anche se molto potente, lo standard quasi de facto, anche in corso di standardizzazione sotto altro nome); se vuoi una cosa più user-friendly, io ho usato un altro linguaggio di descrizione chiamato api blueprint che è quello usato in tool come apiary: https://apiary.io/. poi se serve esistono vari servizi web di "traduzione" da un linguaggio di descrizione all'altro...

hth,

irene

[Irene Celino]

La mia impressione è che tu abbia una sola api con 5 metodi get... Qualcosa del tipo http://stesso-percorso/metodo.
Ad ogni modo, visto che mi sembra che i metodi siano in qualche modo collegati, io farei un documento solo per tutti e 5.

[Alberto]

Fatto! Alla fine ho documentato i campi del JSON con JSON Schema. Grazie a tutti. Se siete interessati a vedere cosa ho combinato: (richiede login)

http://app.apiary.io/opencarecc 

Sicuramente può essere migliorata, ma si vede anche di peggio in giro. :-)

L'unica cosa che non capisco è come esportare il file. L'unico modo chiaro è facendo un push su GitHub, ma non funziona se non hai poteri di admin sul repo. Sto aspettando che i miei sodali me li diano... 

[Alfredo Serafini]

tanto per aggiornare il tema:

"...indeed, Apiary joined OAI last year and added support for Swagger to their tools. It looks like the HTTP API space is consolidating around OAS. "(Open API Initiative aka swagger)
https://www.infoq.com/news/2017/05/api-raml-oas

[Paolo Riva]

Ciao,

anche noi stiamo valutando delle possibilità di integrare il nostro sistema di API in node.js su Swagger.

Tra l'altro ci sono una multitudine di plugin in merito: https://github.com/swagger-api/swagger-node

Ciao Paolo.

--

Hai ricevuto questo messaggio perché sei iscritto al gruppo "Spaghetti Open Data" di Google Gruppi.

Per annullare l'iscrizione a questo gruppo e non ricevere più le sue email, invia un'email a spaghettiopend...@googlegroups.com.

Visita questo gruppo all'indirizzo https://groups.google.com/group/spaghettiopendata.

Per visualizzare questa discussione sul Web, visita https://groups.google.com/d/msgid/spaghettiopendata/19283629-60eb-44de-b7ff-d7b0bd2f4d8a%40googlegroups.com.

[Alberto]

Grazie Alfredo, molto interessante. 

Io ovviamente ho scommesso sul cavallo sbagliato, documentando in API Blueprint. Va beh, fa niente, è tutta vita. :-) Al prossimo giro mi guardo Swagger e provo a "tradurre".

[Irene Celino]

https://apimatic.io/transformer ;-)

Il giorno 10 maggio 2017 10:07, Alberto <alberto...@gmail.com> ha scritto:

Grazie Alfredo, molto interessante. 

Io ovviamente ho scommesso sul cavallo sbagliato, documentando in API Blueprint. Va beh, fa niente, è tutta vita. :-) Al prossimo giro mi guardo Swagger e provo a "tradurre".

--

Hai ricevuto questo messaggio perché sei iscritto al gruppo "Spaghetti Open Data" di Google Gruppi.
Per annullare l'iscrizione a questo gruppo e non ricevere più le sue email, invia un'email a spaghettiopendata+unsubscribe@googlegroups.com.
Visita questo gruppo all'indirizzo https://groups.google.com/group/spaghettiopendata.

Per visualizzare questa discussione sul Web, visita https://groups.google.com/d/msgid/spaghettiopendata/b2b8d9e7-ffbb-4614-9ed4-4d356af3e6d8%40googlegroups.com.

Per altre opzioni visita https://groups.google.com/d/optout.

[Alberto]

Irene, sei una leggenda. :-)

Anche se, ricorda: io sono un newbie. Ho documentato API esattamente una volta. Forse fare una traduzione a mano una volta mi lascia un'infarinata di Swagger, che poi male non mi fa. 

[Irene Celino]

sissì, certo, lungi da me suggerire di non imparare swagger, anzi!

so però che swagger è molto meno "user friendly" di blueprint, che è il motivo per cui anche io ho usato blueprint per la documentazione di alcune mie api (anche io sono una newbie: ho documentato api esattamente 2 volte). al momento documentare mi serviva per comunicare con un altro sviluppatore che le api le doveva invocare, quindi quello che mi interessava era il documento "human readable" di documentazione api, non il suo formato machine-readable.

quando invece l'interoperabilità con il resto del mondo sarà un requisito, certamente sarà molto più sensato che io usi swagger/open api. diciamo che farò l'investimento di impararmi la sintassi di swagger/open api quando lo standard sarà un po' più consolidato... che io sappia, ci sono in giro n versioni di swagger non esattamente uguali, visto che il processo di standardizzazione è ancora in corso (ma alfredo certamente ne sa di più). non essendo il focus delle mie attività di ricerca, fare l'investimento per imparare swagger per me al momento può attendere :-)

Il giorno 10 maggio 2017 11:21, Alberto <alberto...@gmail.com> ha scritto:

Irene, sei una leggenda. :-)

Anche se, ricorda: io sono un newbie. Ho documentato API esattamente una volta. Forse fare una traduzione a mano una volta mi lascia un'infarinata di Swagger, che poi male non mi fa. 

--

Hai ricevuto questo messaggio perché sei iscritto al gruppo "Spaghetti Open Data" di Google Gruppi.
Per annullare l'iscrizione a questo gruppo e non ricevere più le sue email, invia un'email a spaghettiopendata+unsubscribe@googlegroups.com.
Visita questo gruppo all'indirizzo https://groups.google.com/group/spaghettiopendata.

Per visualizzare questa discussione sul Web, visita https://groups.google.com/d/msgid/spaghettiopendata/5b4da442-dd11-4f67-8dba-85d734627dff%40googlegroups.com.

Per altre opzioni visita https://groups.google.com/d/optout.

[Alfredo Serafini]

oh non volevo disincentivarvi ad usare blueprint (anzi grazie ad Irene per il tool, lo faccio girare! :-)) ma far girare la buona notizia che i tre modelli sembrano via via convergere (swagger, blueprint, RAML). Se integrano per bene jsonschema (cosa che per ora va fatta un po' a manina, o -come piace dire ad Alberto "a martellate" :-)) siamo tutti a cavallo e il mondo è almeno poco poco un posto migliore eheh...

Per annullare l'iscrizione a questo argomento, visita https://groups.google.com/d/topic/spaghettiopendata/2V8BwPJWUVo/unsubscribe.

Per annullare l'iscrizione a questo gruppo e a tutti i suoi argomenti, invia un'email a spaghettiopendata+unsubscribe@googlegroups.com.

Visita questo gruppo all'indirizzo https://groups.google.com/group/spaghettiopendata.

Per visualizzare questa discussione sul Web, visita https://groups.google.com/d/msgid/spaghettiopendata/CAJMhNZYUmpzFrE3R2CYeGA%2BfGSNJFN6FGG%3DTyWAdFcZdVj5Svg%40mail.gmail.com.