API RESTful, hypermedia e JSON:API

[jenkin]

Ciao gentaglia,

grazie all'influenza ho finalmente letto il buon libro "RESTful Web APIs" di Amundsen et al. che avevo da (troppo) tempo nell'e-reader e ho scoperto e imparato un sacco di robe.

Mi interesserebbe ora capire lo stato dell'arte attuale su questi temi, non tanto riguardo la parte concettuale, quanto quella implementativa. Non solo per capire se e quando usarli, ma anche per mettere alla prova sul campo la mia comprensione della teoria... :)

Per esempio mi sembra che il recentemente stabile progetto JSON:API (http://jsonapi.org) sia molto interessante da diversi punti di vista, ma non mi è chiaro se e come implementi l'hypermedia constraint (https://en.wikipedia.org/wiki/HATEOAS). Inoltre mi pare che manchi di una specifica per descrivere struttura e semantica delle risorse (l'attributo "attributes") e infatti c'è una discussione sulla possibile integrazione con JSON-LD (https://github.com/json-api/json-api/issues/587). Sono però un po' confuso: JSON-API è un'alternativa a robe come Hydra (http://www.markus-lanthaler.com/hydra/) o è un'altra cosa?

L'idea di API che si descrivono da sole e client che le navigano autonomamente è affascinante, ma ci sono esempi veri funzionanti? Che magari integrino anche il mondo dei linked data? O poi in realtà è ancora tutto documentation-based?

Roba tecnica, lo so, chiedo scusa ai non tecnici della lista (ma sono concetti che usate inconsapevolmente tutti i giorni ogni volta che cliccate su un link, sappiatelo).

Grazie, Buon anno a tutti! :)

[Alfredo Serafini]

ciao Alessio, rispondo al volo quindi scusami la scarsa sintesi

il tema porta con sè tante cose che è difficile sintetizzare in pochi punti.

Al momento secondo me i descrittori più interessanti sono:

• machine-human: OpenAPI (swagger), se pensiamo alla "documentazione in linea" (in realtà consente anche di eseguire query e predisporre snippet con esempi, cosa che non c'è in altre specifiche) dedicata agli sviluppatori
• machine-machine: Hydra, che si sta evolvendo molto anche grazie all'apporto della comunità JSON-LD (molti che ci sono dietro sono attivi su entrambe)

Entrambi hanno diverse implementazioni curate ed attive, chiaramente però mentre swagger è integrato nativamente in un bel po' di progetti e prodotti, hydra è ancora un po' relegato ad ambiti di nicchia.
D'altro canto se parliamo di client autonomi, spesso immaginiamo Agenti dotati di obiettivi autonomi, il che non necessariamente è vero: già solo scorrere elenchi enormi di risorse via RESTful, cercando di identificare immagini pubblicate in una certa data ida un certo utente potrebbe essere un esempio di piccola attività programmabile, implementabile con un uso appropriato di RESTful, e decisamente più efficace se supportata da strumenti come hydra. Non serve necessariamente immaginarsi ricerche con AI per intenderci, o partire per la tangente con speculazioni sulle ontologie. In questo senso potremmo immaginare dei crawler/spider, o altro genere di agenti, ma anche guardare a quanto di tutto ciò sia stato implementato nelle funzionalità di un browser a mio avviso aiuta a schiare le idee.

Se consideriamo i browser come client, manca un "browser semantico" (!), o meglio l'integrazione nativa all'interno dei browser attuali delle capacità di risolvere in autonomia le API, largamente auspicata nell'ambito del web semantico e dei linked data poi da almeno una decina d'anni. Al di là di applicazioni specifiche (che quindi "interrompono" la coerenza e la strategia di navigazione, e quindi di riflesso anche l'integrazione naturale delle informazioni) o di plugin (di solito dedicati "soltanto" alle entities, vedi il vecchissimo PiggyBank di simile già nel 2006) in genere il browser come client offre poche chance di utilizzo diretto di questi descrittori, a tutt'oggi. Un esempio un po' fuori tema ma secondo me emblematico è quello di OpenSearch (http://www.opensearch.org/Home) che pur esistendo da tempo non vedo granché integrato in giro, per dire.

Oppure dell'uso sensato dei tag <link> per la creazione di TOC di navigazione (a suo tempo, intorno al 2005 Opera implementava un menù orizzontale che descriveva le risorse disponibili, ma non ricordo altri esempi) o ancora e più efficacemente l'utilizzo sensato di link tramite RDFa. Il problema secondo me è fortemente legato all'uso degli standard, per molto tempo disincentivato dalle implementazioni catastrofiche (vedi explorer) che per anni hanno reso impossibile costruire anche solo dei rendering HTML robusti, figuriamoci integrare cose che "non si vedono". E che in realtà incidono incredibilmente sulle esperienze di navigazione, in termini di "affordance" e "trovabilità" dei dati. A mio avviso giacché HTML5 prescrive un algoritmo di parsing per HTML e l'uso dei tag predispone maggiore semantica, c'è speranza che questo via via induca i browser a cercare di nuovo questo genere di implementazioni, per migliorare l'esperienza utente.

Tutto ciò è apparentement fuori tema, ma io credo invece sia uno dei driver "forti" per spingere anche chi fornisce servizi ed implementa le API a farlo in maniera machine-machine, poiché se tra i vari agenti che dovranno interrogare le API c'è la possibilità di avere dei veri e propri browser, evidentemente non si può pensare di implementare versioni troppo "ristrette" delle descrizioni, o peggio troppo personalizzate. 

Al momento JSONAPI lo inserirei in questa prospettiva nello stesso gruppo di descrittori in cui esistono anche WADL(https://en.wikipedia.org/wiki/Web_Application_Description_Language) e WSDL(https://en.wikipedia.org/wiki/Web_Services_Description_Language) basati su XML, o RAML(https://en.wikipedia.org/wiki/RAML_(software)) basato su YAML, tanto per citare quelli che effettivamente hanno avuto notevole adozione in librerie e framework, Queste librerie possono essere utili per implementare agenti ad-hoc su specifiche API, chiaramente l'idea di una reale autonomia di navigazione è un passo più avanti.

C'è una paginetta wikipedia che prova a riassumerli tutti: https://en.wikipedia.org/wiki/Overview_of_RESTful_API_Description_Languages

i miei 2 cents

Alfredo

[jenkin]

E però Wikipedia ti sconfessa! :D Tu dici che JSONAPI fa parte del mondo di WADL, WSDL e RAML, mentre la pagina https://en.wikipedia.org/wiki/Overview_of_RESTful_API_Description_Languages lo mette nella sezione "data description languages" e non "api description languages"... :)

Io ho capito così:

• voglio descrivere la struttura della mia API -> open api initiative (aka swagger, che però non dice nulla su cosa ritornano le chiamate, a parte un check sulla sintassi personalizzato tipo JSON Schema);
• voglio un formato delle risposte dell'API che sia condiviso -> JSONAPI (che è una vera e proprio "applicazione" JSON, prendendo a prestito il termine dal mondo XML, ma che non dice nulla sugli attributi delle risorse e sui meta);
• voglio descrivere sintatticamente e semanticamente il mio formato dati -> JSON-LD (magari con @context e @id dentro gli attributi delle risorse oppure nei meta della collezione).

Purtroppo mi pare che l'ultima integrazione (JSON-LD dentro le risorse rappresentate à la JSONAPI) non sia standard. Sbaglio?

[Alfredo Serafini]

JSONAPI per me dovrebbe stare con WADL, ed è pure un po' meno espressivo dei formati XML, poiché in generale JSON è un po' povero come esprevvisività semantica. Le integrazioni con JSON-LD fatte come si deve sarebbe interessanti, però non mi risulta ce ne siano standard, infatti hydra è un progetto interessante!
Al solito dipende dagli obiettivi: secondo me andrebbero idealmente predisposte descrizioni "per umani" e "per macchine", entrambe, e con una preferenza alle prime visto che in generale non esistono "davvero" agenti in grado di utilizzare autonomamente le varie API. Per esempio hydra sono riuscito ad usarlo per fare una minima integrazione di dati, ma sono casi particolari, mentre è relativamente frequente programmare cose per consumare certe API e quindi spulciarsi la documentazione.
Come formato condiviso secondo me sono in tal senso meglio i formati XML, ancora, al limite entrambi

--
Hai ricevuto questo messaggio perché sei iscritto al gruppo "Spaghetti Open Data" di Google Gruppi.
Per annullare l'iscrizione a questo argomento, visita https://groups.google.com/d/topic/spaghettiopendata/5E_9BEztnxQ/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 altre opzioni visita https://groups.google.com/d/optout.

[Piero Savastano]

Tema interessante!

Vorrei accodarmi su alcune osservazioni già emerse:

==============

1 - la direzione in cui andiamo è quella di agenti semantici, in grado di navigare autonomamente i dati per fornire delle risposte (o proposte!) agli utenti umani. E' un cavallo di battaglia e promessa chiave dei linked data, che ne hanno il potenziale... ma la fattibilità è ancora all'orizzonte.

Un progetto interessante che offre l'aroma di questi agenti sono i Linked Data Fragments. L'idea è quella di far girare le query SPARQL direttamente nel browser, abbandonando l'idea infantile che ci debba essere un server pieno di dati in grado di soddisfare qualsiasi richiesta. Oltre alla decentralizzazione dei dati si spinge per decentralizzare il calcolo, spostando il peso sul client e rendendolo via via sempre più "smart".

Il progetto è sviluppato nella stessa community W3C che si occupa di Hydra.

==============

2 - Gli standard sono importanti perchè è quello l'unico modo di decentralizzare e generalizzare i dati, e di conseguena le AI che li navigano. Ancora una volta, i linked data offrono la possibilità di definire classi e attributi senza separare i dati dai metadati, perchè tutto è definito online. Esempio, un agente che conosce https://schema.org/CreativeWork può proseguire la sua ricerca, quello che non lo conosce guarda il link stesso e lo trova definito.

Quest'ultimo meccanismo, ossia utilizzare i link per descrivere non solo le risorse ma anche i metadati è stato scimmiottato da varie iniziative, tra cui JSONAPI. Molto pratico e facile da capire, ma una banalizzazione degli strumenti che abbiamo a disposizione e che derivano da decenni di standardizzazione.

Hydra invece, cito il sito:

"is an effort to simplify the development of interoperable, hypermedia-driven Web APIs. The two fundamental building blocks of Hydra are JSON‑LD and the Hydra Core Vocabulary"

Cioè utilizza JSON-LD (formato JSON per descrivere i linked data raccomandato dal W3C) e il vocabolario Hydra, inteso come insieme di URI che definiscono classi, attributi e azioni riguardanti il dominio delle REST API. Il tutto perfettamente inquadrato nel framework dei linked data, senza reinventare la ruota.

Per cui se mi devo schierare, Hydra tutta la vita.

============

Saluti e grazie degli interventi,

Piero

[jenkin]

Ehi, forse comincio a capire! :)

Però mi pare che JSONAPI e Hydra affrontino due problemi abbastanza diversi, come espresso anche in questa discussione: https://lists.w3.org/Archives/Public/public-hydra/2016Jan/0001.html.

E questo semplice esempio pratico suggerisce anche un modo per coniugare Hydra con JSONAPI: https://www.programmableweb.com/news/how-to-build-hypermedia-apis-json-ld-and-hydra/analysis/2015/07/30.

In pratica mi sembra che JSONAPI indichi il formato dei JSON scambiati, descrivendo non solo le risorse, ma anche le dipendenze tra risorse.

Gli manca la descrizione semantica delle risorse, ma può essere integrato con JSON-LD (come mostrato nell'esempio sopra).

Gli manca l'hypermedia, cioè la descrizione di cosa può fare il client dopo aver ottenuto la risposta, e qui entra in gioco Hydra, con il suo vocabolario.

Secondo me non è così strano pensare a una specifica che concili tutte queste esigenze, i pezzi mi pare ci siano tutti...

[Alfredo Serafini]

In pratica mi sembra che JSONAPI indichi il formato dei JSON scambiati, descrivendo non solo le risorse, ma anche le dipendenze tra risorse.

Gli manca la descrizione semantica delle risorse, ma può essere integrato con JSON-LD (come mostrato nell'esempio sopra).

Gli manca l'hypermedia, cioè la descrizione di cosa può fare il client dopo aver ottenuto la risposta, e qui entra in gioco Hydra, con il suo vocabolario.

si la parte insomma HATEOAS del RESTful! per di più hydra la mette a disposizione in modo semantico: un agente potrebbe in teoria decidere di navigare tra rappresentazioni o persino azioni differenti, in base alle proprie capacità. 

Per questo ti suggerivo di considerare JSONAPI nello stesso gruppo di WADSL. Parliamoci chiaro: XML non va più "di moda" e si cercando soluzioni basate su JSON :-) Però JSON ha dei limiti oggettivi: tanto è semplice da utilizzare, quanto impreciso nella descrizione di cose del genere. Un buon controesempio è JSONLD, ma usrlo bene richiede accorgimenti che la maggiorparte degli smanettoni non vogliono adottare. Con le dovute differenze di contesto io vedo fortissime analogie con il parsing di HTML5: se vuoi un approccio pragmatico scrivi cose semplici e le usi in due minuti e te le scordi. Però quello che produci non avrà una buona semantica, per produrre la quale devi investire nella standardizzazione e nella semplicità, che come è noto richiede tempo. Così come spesso si accroccano visualizzazione con zuppe di div, a livello di API spesso si preferisce aggiungere un pezzo che fa una cosa specifica e risolve un problema locale, senza preoccuparsi troppo del fatto che questo possa impattare sull'intero ecosistema dei dati. 

Qualcosa di avanzato è all'orrizzonte sull'interscambio dei servizi, ad esempio "semantizzando" cose come USDL o in generale il provisioning, ad esempio, così come esistono diversi approcci MDM tramite grafi e/o semantica, non necessariamente basati su interfacce web. I client -intesi come mero scambio "in lettura" dei dati- sono solo la punta dell'iceberg, ma c'è tantissima strada ancora da fare. La cosa positiva è che togliendo il cappelo del web semantico e mettendo quello dei linked data la percezione generale è stata di qualcosa di più accessibile e quindi stanno emergendo nuovi interessi e tentativi di implementazione :-), ma di queste tematiche si parla veramente da diversi anni. Già RSS e i pingback integravano elementi del genere (parlo del 2005), così come HATEOAS prescrive(rebbe) URI assoulute (come i linked data, ma spostando la'ttenzione dalle risorse a qualcosa di più sfuggente, catturabile dalle azioni sui dati).

Condivido con Piero l'interesse per i fragment, che costituiscono una prima soluzione pragmatica anche qui a un tema di cui leggo in letteratura almeno dal 2005 (cioè "spezzettare" le query SPARQL, garantendo maggiore scalabilità) e diverse possibilità di riuso, non ultime le navigazioni che un po' tutti abbiamo tentato con il ben noto pattern "follow your nose". 

 

Secondo me non è così strano pensare a una specifica che concili tutte queste esigenze, i pezzi mi pare ci siano tutti...

Si e no, secondo me. In generale la programmazione di agenti -davvero- intelligenti non è banale, perché presupporrebbe non solo dati efficacemente autodescrittivi, ma anche un po' di capacità di ragionamento sui dati, e più si va in una direzione del genere di solito, più si è costretti a progettare cose (o a farle apprendere) su domini specifici bene o male. Anche per le API il discorso è simile, ancora è difficile immaginare qualcosa di genral-purpose che possa capire come interagire, e chiaramente se devi comunque istruire e/o programmare il comportamento dell'agente ti conviene investire energie nel farlo funzionare meglio, invece che nel renderlo "troppo" generale.

Secondo me però fintanto che continueremo a raccontarci l'idea che sia più facile ragionare (soltanto) a tabelle anche questi standard resteranno limitati. 

@Piero 

la parte di hypermedia è difatti la vera sfida, già da alcuni anni: si potrebbero fare cose molto interessanti ed utili!

[Matteo Brunati]

Il giorno martedì 10 gennaio 2017 13:07:32 UTC+1, jenkin ha scritto:

Ehi, forse comincio a capire! :)

Però mi pare che JSONAPI e Hydra affrontino due problemi abbastanza diversi, come espresso anche in questa discussione: https://lists.w3.org/Archives/Public/public-hydra/2016Jan/0001.html.

E questo semplice esempio pratico suggerisce anche un modo per coniugare Hydra con JSONAPI: https://www.programmableweb.com/news/how-to-build-hypermedia-apis-json-ld-and-hydra/analysis/2015/07/30.

Wow Alessio, quel thread che hai indicato è davvero bello, consiglio di leggere tutta la discussione che ne emerge: utile per capire i retroscena del pro e vs di quello che è successo in questi anni allo stack tecnologico del Semantic Web/Linked Data.
Specie questa presentazione:

• https://vanthome.github.io/rest-api-essay-presentation/rest_apis.html#1

matt

ps - bel thread, davvero

[jenkin]

Grazie matt, in effetti non ho letto con attenzione *tutta* la discussione che ho linkato io stesso, recupererò dando un'occhiata anche alle slide...

mi pare comunque che alla domanda: "uh, devo progettare una API, qual è il modo migliore?" la risposta sia sempre "boh, dipende, ci sono n -> \inf modi diversi"... :)

[Matteo Brunati]

Il giorno martedì 10 gennaio 2017 12:22:49 UTC+1, Piero Savastano ha scritto:

Tema interessante!

Confermo :)

 

==============

2 - Gli standard sono importanti perchè è quello l'unico modo di decentralizzare e generalizzare i dati, e di conseguena le AI che li navigano. Ancora una volta, i linked data offrono la possibilità di definire classi e attributi senza separare i dati dai metadati, perchè tutto è definito online. Esempio, un agente che conosce https://schema.org/CreativeWork può proseguire la sua ricerca, quello che non lo conosce guarda il link stesso e lo trova definito.

Quest'ultimo meccanismo, ossia utilizzare i link per descrivere non solo le risorse ma anche i metadati è stato scimmiottato da varie iniziative, tra cui JSONAPI. Molto pratico e facile da capire, ma una banalizzazione degli strumenti che abbiamo a disposizione e che derivano da decenni di standardizzazione.

Hydra invece, cito il sito:

"is an effort to simplify the development of interoperable, hypermedia-driven Web APIs. The two fundamental building blocks of Hydra are JSON‑LD and the Hydra Core Vocabulary"

Cioè utilizza JSON-LD (formato JSON per descrivere i linked data raccomandato dal W3C) e il vocabolario Hydra, inteso come insieme di URI che definiscono classi, attributi e azioni riguardanti il dominio delle REST API. Il tutto perfettamente inquadrato nel framework dei linked data, senza reinventare la ruota.

Per cui se mi devo schierare, Hydra tutta la vita.

============

Saluti e grazie degli interventi,

Piero

Mi accodo al volo: c'è un gran bel doc nel community group su JSON-LD, che merita attenzione perché chiarisce un po' di cosette (almeno a livello politico avvicina JSON-LD ad Hydra ufficialmente, e non è scontato):

• http://json-ld.org/spec/latest/json-ld-api-best-practices/

In particolare il punto 7[1] è notevole:

Describe the use of schema.org Actions and work in Hydra.

Che è proprio quello che si accennava: e stavolta forse c'è quel minimo compromesso storico (il principio del Least Power di buon design del Web) applicato all'hypermedia. Non so, è una sensazione.

Ma ci sono cose interessanti in giro, tipo questa:

• http://t-code.pl/blog/2016/04/introducing-heracles/
  

matt

[1] - http://json-ld.org/spec/latest/json-ld-api-best-practices/#describe-api-affordances
 

[Alfredo Serafini]

sottoscrivo, il punto che cercavo di sottolineare è proprio per le affordance: di solito se ne parla nella prospettiva dell'agente umano (utente insomma :-)) però un principio analogo vale per gli agenti software... il problema è sempre quello della programmabilità, cioè del programmare la capacità di individuazione, e non la sequenza specifica di azioni. non è banale ma è un bel tema.

Sul fatto che si veleggi nella direzione di un buon compromesso condivido pure, io ho solo più di qualche dubbio sul fatto che la forma attuale di hydra possa mai diventare mainstream: a quanto leggo sulla community c'è anche lì un bel po' di fermento su quelli che potrebbero essere i prossimi passi.

Faccio un esempio pratico: se uso swagger posso produrre automaticamente dei mock da cui sviluppare il mio software, con hydra allo stato attuale di fatto no, questo è un po' paradossale :-)
Per come la vedo io è molto probabile che si evolvano i due standard in una direzione intermedia, però è più facile adeguare le macchine alle descrizioni per esseri umani che viceversa

--

[Alfredo Serafini]

ciao 

segnalo anche questa bella presentazione di Ruben Verborgh:

"A Bird’s-Eye View of the Web" (http://rubenverborgh.github.io/WebFundamentals/birds-eye-view/#title) 

che è abbastanza a tema con il thread

saluti,

A.

[Piero Savastano]

Grazie degli spunti ragazzi :)
Difficile capire cosa succederà e come, ma il trend generale è chiarissimo.

--

Hai ricevuto questo messaggio perché sei iscritto al gruppo "Spaghetti Open Data" di Google Gruppi.
Per annullare l'iscrizione a questo argomento, visita https://groups.google.com/d/topic/spaghettiopendata/5E_9BEztnxQ/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 altre opzioni visita https://groups.google.com/d/optout.

--

http://pieroit.org/portfolio

+39 320 09 23 630

[Alfredo Serafini]

Aggiungo per arricchire la discussione con gli ultimi sviluppi, che RAML e swagger / Open API stanno via via convergendo, tanto che pure apiary sta introducendo OAS
https://www.infoq.com/news/2017/05/api-raml-oas

Il giorno sabato 7 gennaio 2017 12:59:52 UTC+1, Alessio Cimarelli ha scritto: