api.medialibrary.it versione 1.0 [ultima revisione: ]

Transcript

1 api.medialibrary.it versione 1.0 [ultima revisione: ] 1

2 Indice 1. Definizioni 2. Architettura generale delle API MLOL 3. L attivazione delle API MLOL 3.1. Sicurezza e autenticazione 3.2. La licenza MLOL API 4. Risorse permanenti: ingestione e consultazione dei media 4.1. Quali tipologie di media MLOL rientrano nelle risorse permanenti 4.2. Ingestione dei media 4.3. Consultazione dei media 5. Risorse temporanee: widget di ricerca, iframe di navigazione delle risorse e consultazione dei media 5.1. Backward compatibility del widget Quali tipologie di media MLOL rientrano nelle risorse temporanee 5.3. Funzioni di ricerca e widget 5.4. L iframe MLOL e la consultazione dei media 6. Altre funzioni 6.1. Liste di media 6.2. Dati dell utente 6.3. Altro 7. Il sistema di SSO delle API MLOL Appendice 1. Tipologie di media supportate 2

3 1. Definizioni cliente gestore LMS per conto della biblioteca o del sistema bibliotecario aderente a MLOL (ad esempio: Comperio è il cliente per conto del Sistema bibliotecario bresciano che aderisce a MLOL) software cliente portale OPAC (o similare) nel quale il cliente intende integrare le API MLOL risorse permanenti risorse che possono essere ingestite dall OPAC sotto forma di scheda catalografica risorse temporanee risorse temporanee (o sottoscrizionali) sono invece quelle per cui l ingestione non è prevista iframe MLOL versione semplificata di MLOL specifica per il servizio API, contenente le principali funzioni di ricerca e adatta ad essere inclusa in un iframe portale API MLOL versione semplificata di MLOL specifica per il servizio API, pensata per l accesso dalla API alle schede media MLOL e alla consultazione dei media stessi widget MLOL piccolo box che contiene i risultati della ricerca su MLOL suddivisi per tipologia, e i relativi URL a MLOL (v.1.0) o all iframe (v.2.0); può essere creato a partire dall output dei servizi Ricerca e RicercaAv 3

4 2. Architettura generale delle API MLOL Il servizio espone buona parte delle funzioni attulamente disponibili all interno dei portali MediaLibraryOnLine (MLOL). Il servizio è accessibile all indirizzo (connessione sicura obbligatoria). Il servizio è di tipo SOAP e l output è in formato XML. Per quanto riguarda le risorse permanenti la struttura del servizio è la seguente: i record vengono ingestiti, diventando così delle schede catalografiche all interno del software cliente dalla scheda catalografica è possibile passare alla scheda del media nel portale API MLOL e alla consultazione del media stesso Per quanto riguarda le risorse temporanee la struttura del servizio è la seguente: ogni ricerca all interno del software cliente viene effettuata anche su MLOL, tramite un apposita funzione questa funzione restituisce tutti gli elementi necessari per creare, sempre all interno del software cliente, il widget MLOL dei risultati relativi alla ricerca divisi per tipologia nell ultima versione (2.0), i link all interno del widget devono rimandare ad una pagina, sempre all interno del software cliente, contenente una istanza dell iframe MLOL inizializzata con i risultati della ricerca all interno dell iframe sarà possibile affinare la ricerca o effettuarne di nuove, e alla fine si potrà proseguire con la consultazione del media nel portale API MLOL qualora si decida di utilizzare il widget nella versione precedente (1.0) gli URL rimanderanno direttamente ai risultati della ricerca nel portale MLOL del Sistema Bibliotecario aderente, come già avviene per chi ha implementato la versione precendente delle API Oltre alle funzioni relative alla ricerca dei record, nel software cliente è possibile integrare storico prestiti utente liste media standard (novità, più consultati) 4

5 3. L attivazione delle API MLOL 3.1. Sicurezza e autenticazione del servizio che utilizza le API Il servizio può essere utilizzato solo tramite una connessione sicura (https). Qualunque richiesta non sicura avrà in risposta un ssl_error. Per essere autenticati dal web service, e poterlo quindi interrogare con successo, è necessario includere in ogni richiesta un parametro valido. Una chiave specifica viene comunicata da MLOL ai clienti che intendono utilizzare il servizio. Qualunque richiesta priva di queste credenziali o contenente credenziali errate avrà in risposta un authentication_error Parametri comuni chiave univoca per l utilizzo della API comunicata al cliente che richieda di utilizzare le API. parametro obbligatorio in tutti i metodi Risposte del servizio L esito della chiamata di tutti i servizi può essere verificato all interno dell XML nel nodo di primo livello <status>. In caso di errori, se necassario, allo stesso livello può essere presente un ulteriore nodo <error> con una spiegazione più dettagliata dell errore in questione. Di seguito una tabella dei possibili valori di <status>: Valore ok ssl_error authentication_error parameter_error service_error Significato Richiesta valida La richiesta ha utilizzato una connessione non sicura La richiesta non contiene credenziali di autenticazione corrette La richiesta non contiene parametri obbligatori o contiene valori errati Il servizio ha incontrato un problema interno o è momentaneamente non disponibile. Riprovare in seguito e scrivere a info@medialibrary.it in caso di persistenza dell errore. 5

6 3.2. La licenza MLOL API Per gli aspetti legali inerenti all utilizzo delle API MLOL, si faccia riferimento al documento specifico Licenza API MLOL. 6

7 4. Risorse permanenti: ingestione e consultazione dei media 4.1. Quali tipologie di media MLOL rientrano nelle risorse permanenti Rientrano nelle risorse permanenti quei media che hanno affinità con le risorse che di solito si trovano già nei cataloghi del software cliente, e che sono state in qualche modo acquisite (anche commercialmente) in modo permanente dal cliente, e pertanto non rischiano di sparire da un giorno all altro disorientando l utente. Queste risorse coincidono più o meno con la totalità dei media nelle tipologie MLOL E Book Download e Audiolibri Download, in cui la totalità è ovviamente relativa alle risorse disponibili per il portale del cliente (es.: se l e book X non compare nel portale MLOL del sistema bibliotecario Y, allora non comparirà neanche nella lista di quelli che è possibile ingestire con la relativa al cliente Y) Ingestione dei media GetRecords Restituisce i record da ingestire. L'update è incrementale rispetto all'ultima chiamata, a meno che full_export non sia impostato a true. portal_id chiave identificativa del cliente del portale MLOL di riferimento la chiave di riferimento per il cliente verrà comunicata da MLOL il codice del portale di riferimento per il cliente verrà comunicato da MLOL. format formato dell output formato dell XML resituito; i valori possibili sono xmldc (simil Dublin Core, più leggibile) e xmlmarc (TurboMARC XML, meno leggibile ma più adatto per l importazione sotto forma di record MARC) full_export indica se esportare tutti i record o sono le ultime modifiche true per esportare tutto (da utilizzare in casi eccezionali), false per avere solo i record aggiunti / rimossi / modificati dall ultima volta che il software cliente ha utilizzato questa funzione Esempio di output (formato xmldc): <media_list> <status>ok</status> <id> </id> <active>1</active> <created> :10:40</created> <modified> :10:40</modified> <interlibrary>1</interlibrary> 7

8 <dc_title>il fu Mattia Pascal</dc_title> <dc_creator>pirandello, Luigi</dc_creator> <dc_publisher>bur</dc_publisher> <dc_subject>letteratura E STUDI LETTERARI</dc_subject> <dc_subject>narrativa E ARGOMENTI CORRELATI</dc_subject> <dc_subject>letteratura italiana</dc_subject> <dc_subject>narrativa CLASSICA (PRIMA DEL 1945)</dc_subject> <dc_description>premio NOBEL nel 1934, tradotto in tutto il mondo, Pirandello è autore capitale della letteratura, non solo italiana, del Novecento, di cui ha rispecchiato, in modo tormentato e geniale, evoluzione e crisi. In una vasta produzione fatta di novelle, romanzi, opere teatrali, Pirandello si presenta come il creatore di un mondo di inesauribile vigore fantastico e di sorprendente modernità. Il fu Mattia Pascal, pubblicato nel 1904, è il più importante tra i romanzi dello scrittore siciliano. </dc_description> <dc_language>italiano</dc_language> <dc_type>e Book Download</dc_type> <dc_format>pdf/epub con DRM Adobe</dc_format> <url_cover> <url_logo_pub> <isbn_paper> </isbn_paper> <isbn_pdf> </isbn_pdf> <isbn_epub> </isbn_epub> <url_preview> <lia>0</lia> <lia_url></lia_url>... </media_list> NOTE SUI CAMPI DELL XML <active> indica se il titolo è attivo. Se un titolo arriva con questo campo impostato a 0 è necessario rimuoverlo o disattivarlo anche nel catalogo del software cliente. <interlibrary> se impostato a 1 il titolo non è nel catalogo proprietario del sistema ma è visibile come risultato del servizio di prestito interbibliotecario. Per questi titoli si consiglia di mostrare il bollino disponibile all'indirizzo <url_preview> può contenere l URL ad un piccolo estratto del titolo ad accesso libero, che può essere messo a disposizione dell utente. <lia> se impostato a 1 il titolo fa parte dei Libri Italiani Accessibili. Per questi titoli si consiglia di mostrare il bollino disponibile all'indirizzo <lia_url> per i titoli LIA questo campo può contenere l'url della scheda del libro sul sito libriitalianiaccessibili.it 8

9 4.3. Consultazione dei media OpenMedia Avvia la consultazione del media selezionato nel Portale API MLOL. L utente deve essere autenticato nel software cliente, che deve trasmettere l informazione relativa allo username. In mancanza di questo dato si avrà un errore. Se l utente non è autenticato, prima di procedere sarà necessario richiedergli l autenticazione. Per procedere con la consultazione è necessario chiamare chiamare in POST (e con protocollo https) la pagina <url> passando il parametro <param_name> con valore <param_value>. portal_id chiave identificativa del cliente del portale MLOL di riferimento la chiave di riferimento per il cliente verrà comunicata da MLOL il codice del portale di riferimento per il cliente verrà comunicato da MLOL. username nome utente si tratta dello stesso username utilizzato nel software cliente media_id del media ID del media come restituto da GetRecords Esempio di output <media_open> <status><! ok se richiesta corretta o stringa di errore ></status> <url> <param_name>token</param_name> <param_value>adi2387gfs80gb2g8f4</param_value> </media_open> 9

10 5. Risorse temporanee: widget di ricerca, iframe di navigazione delle risorse e consultazione dei media 5.1. Backward compatibility del widget 1.0 Coloro che avessero incluso nel software cliente la precedente versione delle API possono, se preferiscono, far funzionare questa versione esattamente come la vecchia. Di seguito gli accorgimenti da utilizzare: Modificare l indirizzo base di tutti i servizi da ws.medialibrary.it a api.medialibrary.it Il SoapHeader UserCredentials e le relative credenziali non sono più necessari, al loro posto è necessario ottenere da MLOL una Il primo parametro di tutte le funzioni diventa, con tutti gli altri (invariati) a seguire anche l xml dei risultati presenta delle differenze: non ha più un namespace il nodo <stato> ora si chiama <status> il nodo <url> che prima puntava ai risultati della ricerca nel portale MLOL adesso contiene l URL da utilizzare per includere l iframe MLOL il nodo che punta ai risultati della ricerca nel portale MLOL (e quindi da utlizzare se si vuole proseguire con lo stesso tipo di integrazione) si chiama invece <url_mlol> 5.2. Quali tipologie di media MLOL rientrano nelle risorse temporanee Rientrano nelle risorse temporanee (o sottoscrizionali) tutti quei media che non rientrano nella definizione di cui al paragrafo 4.1. Si tratta di risorse che sono disponibili per il cliente perché facenti parte della Collezione Open, o perché il cliente ha sottoscritto una licenza (di solito annuale) per il loro utilizzo. In entrambi i casi quindi potrebbero essere rimosse dal catalogo dopo un certo periodo di tempo, da cui la definizione di temporanee. 10

11 5.3. Funzioni di ricerca e widget Ricerca (ricerca semplice) keywords idportale chiave identificativa del cliente stringa contenente le parole chiave da cercare del portale MLOL di riferimento la chiave di riferimento per il cliente verrà comunicata da MLOL supporta gli operatori di ricerca più comuni (+,,, *); le parole di 1 o 2 caratteri vengono ignorate. i risultati delle ricerche variano a seconda della disponibilità di alcuni contenuti nel portale selezionato; il codice 1 identifica il portale generale; codici errati vengono interpretati come 1 ; il codice del portale di riferimento per il cliente verrà comunicato da MLOL. I parametri sono tutti obbligatori. Qualunque richiesta non soddisfi questa condizione avrà in risposta un parameter_error RicercaAv (ricerca avanzata) titolo autore editore lingua idtipologia idportale chiave identificativa del cliente stringa da cercare nel campo titolo stringa da cercare nel campo autore stringa da cercare nel campo editore stringa da cercare nel campo lingua di una tipologia specifica del portale MLOL di riferimento la chiave di riferimento per il cliente verrà comunicata da MLOL gli operatori di ricerca (+,, ecc.) vengono ignorati gli operatori di ricerca (+,, ecc.) vengono ignorati gli operatori di ricerca (+,, ecc.) vengono ignorati gli operatori di ricerca (+,, ecc.) vengono ignorati per la lista delle tipologie supportate e i relativi codici identificativi si veda l Appendice 1; codici errati producono un insieme di risultati vuoto. i risultati delle ricerche variano a seconda della disponibilità di alcuni contenuti nel portale selezionato; il codice 1 identifica il portale generale; codici errati vengono interpretati come 1 ; il codice del portale di riferimento per il cliente verrà comunicato da MLOL. 11

12 I parametri e idportale sono obbligatori. Inoltre, almeno uno degli altri 5 parametri deve essere non vuoto. Qualunque richiesta non soddisfi queste condizioni avrà in risposta un parameter_error Output L output del servizio sarà un XML così composto: <status><! ok se richiesta corretta o stringa di errore ></status> <totale><! numero risultati in tutte le tipologie ></totale> <tipologia> <id><! id della tipologia ></id> <nome><! nome della tipologia ></nome> <risultati><! numero risultati in questa tipologia ></risultati> <icona><! URL icona tipologia ></icona> <url><! URL ai risultati della ricerca in iframe MLOL per questa tipologia ></url> <url_mlol><! URL ai risultati della ricerca in portale MLOL per questa tipologia ></url_mlol> </tipologia> <! eventuali altre tipologie > A partire da questo output, è possibile creare il widget di ricerca, che conterrà un serie di righe del tipo: <img src= icona alt= nome /><a href= url_pagina_iframe >nome: risultati</a> in grassetto i campi ottenuti dall output xml. url_pagina_iframe punterà ad una pagina del software cliente in cui verrà inserito l iframe MLOL, di cui parleremo al paragrafo successivo. Per l utilizzo del campo <url_mlol> si veda il paragrafo L iframe MLOL e la consultazione dei media L iframe di ricerca consente di affinare la ricerca effettuata nel software cliente o di effettuarne di nuove, per poi proseguire con la consultazione del media nel Portale API MLOL. Deve essere contenuto in una pagina del software cliente, nella quale presumibilmente occuperà tutto il corpo centrale. Si raccomanda una larghezza di almeno 1024px e un altezza di almeno 600px. L indirizzo sorgente dell iframe è del tipo url&username=username, dove url è il campo <url> ottenuto al paragrafo precedente e username è lo username dell utente all interno del servizio cliente. Se l utente non è autenticato, prima di procedere sarà necessario richiedergli l autenticazione. La consultazione dei media avverrà attraverso gli appositi link al interno del frame, che apriranno all utente una finestra sul Portale API MLOL. 12

13 6. Altre funzioni 6.1. Liste di media TopList Resituisce la lista dei titoli più consultati per una tipologia ed un ente/portale specifico. portal_id type_id chiave identificativa del cliente del portale MLOL di riferimento di una tipologia specifica la chiave di riferimento per il cliente verrà comunicata da MLOL il codice del portale di riferimento per il cliente verrà comunicato da MLOL. per la lista delle tipologie supportate e i relativi codici identificativi si veda l Appendice 1; codici errati producono un insieme di risultati vuoto. Esempio di output: <media_list> <status>ok</status> <pos>1</pos> <id> </id> <dc_title>il fu Mattia Pascal</dc_title> <dc_creator>pirandello, Luigi</dc_creator> <url_cover> <pos>2</pos>... </media_list> NewList Resituisce la lista dei titoli aggiunti di recente per una tipologia ed un ente/portale specifico. chiave identificativa del cliente la chiave di riferimento per il cliente verrà comunicata da MLOL 13

14 portal_id type_id del portale MLOL di riferimento di una tipologia specifica il codice del portale di riferimento per il cliente verrà comunicato da MLOL. per la lista delle tipologie supportate e i relativi codici identificativi si veda l Appendice 1; codici errati producono un insieme di risultati vuoto. Esempio di output: <media_list> <status>ok</status> <pos>1</pos> <id> </id> <dc_title>il fu Mattia Pascal</dc_title> <dc_creator>pirandello, Luigi</dc_creator> <url_cover> <pos>2</pos>... </media_list> 6.2. Dati dell utente UserLoans Resituisce la restituisce la lista dei prestiti effettuati dall'utente, inclusi quelli in corso. L utente deve essere autenticato nel software cliente, che deve trasmettere l informazione relativa allo username. In mancanza di questo dato si avrà un errore. Se l utente non è autenticato, prima di procedere sarà necessario richiedergli l autenticazione. portal_id chiave identificativa del cliente del portale MLOL di riferimento la chiave di riferimento per il cliente verrà comunicata da MLOL il codice del portale di riferimento per il cliente verrà comunicato da MLOL. username nome utente si tratta dello stesso username utilizzato nel software cliente 14

15 Esempio di output: <media_list> <status>ok</status> <id> </id> <dc_title>il fu Mattia Pascal</dc_title> <dc_creator>pirandello, Luigi</dc_creator> <dc_type>e Book Download</dc_type> <acquired> </acquired> <expired> </expired> <interlibrary>0</interlibrary>... </media_list> 6.3. Altro GetTypes Resituisce la lista delle tipologie di media abilitate per il portale cliente, con i relativi codici e icone. portal_id chiave identificativa del cliente del portale MLOL di riferimento la chiave di riferimento per il cliente verrà comunicata da MLOL il codice del portale di riferimento per il cliente verrà comunicato da MLOL. Esempio di output <media_list> <status><! ok se richiesta corretta o stringa di errore ></status> <tipologia> <id>110</id> <nome>audio Open</nome> <icona> </tipologia> <tipologia> <id>120</id> <nome>audio Streaming</nome> <icona> </tipologia>... </media_list> 15

16 7. Il sistema di SSO delle API MLOL Le nostre API consentono all utente del software cliente di passare dal proprio ambiente a quelli MLOL rimanendo sempre autenticato, senza la necessità di reinserire le sue credenziali. Questa funzionalità prende il nome di Single Sign On (SSO). Per garantire la sicurezza delle credenzial, la password non viene mai scambiata, in quanto MLOL si fida dell autenticazione effettuata all interno del software cliente. Inoltre, tanto lo username quanto altri possibili dati sensibili vengono sempre scambiati dietro connessione sicura (SSL) e mai in chiaro. 16

17 Appendice 1. Tipologie di media supportate Nota: questi valori potrebbero essere soggetti a variazioni in futuro, si consiglia di fare riferimento ai dati restituiti da GetTypes. ID tipologia Nome tipologia 110 Audio Open 120 Audio Streaming 210 Video Open 220 Video Streaming 230 Film Download 310 E Book Open 320 E Book Streaming 330 E Book Download 400 E Learning 500 Banche dati 600 Quotidiani e Periodici 710 Audiolibri Open 720 Audiolibri Streaming 730 Audiolibri Download 800 Immagini 17