PHAIDRA API - giulioturetta/la-biblioteca-dei-dati GitHub Wiki

1. PHAIDRA API

Obiettivi

  • Imparare come eseguire operazioni con le PHAIDRA API
  • Costruire le URL delle richieste
  • Analizzare le risposte restituite

Sommario


Le API di PHAIDRA

PHAIDRA espone i propri servizi e contenuti tramite delle web API.

Utilizzando le API si possono ottenere i metadati degli oggetti digitali in PHAIDRA come documenti XML o in formato JSON (JavaScript Object Notation).

Le API permettono anche di ottenere, ad esempio, gli oggetti membri di una collezione, gli identificatori di un oggetto e di eseguire operazioni, previa autenticazione, di modifica e creazione di oggetti digitali in PHAIDRA.

Le API possono compiere operazioni in PHAIDRA mediante delle richieste HTTP a delle URL.

Le operazioni di dividono in operazioni di GET per ottenere informazioni da PHAIDRA ed operazioni di POST, solitamente autenticate, per apportare modifiche a PHAIDRA.

Le documentazione completa delle API di PHAIDRA è consultabile all’indirizzo https://github.com/phaidra/phaidra-api/wiki/Documentation.


Comporre le URL per interrogare le PHAIDRA API

https://phaidra.cab.unipd.it/api/ + azione + ? + nome_parametro=valore_parametro + & + ...

Baseurl delle PHAIDRA API
  • Ogni chiamata alle PHAIDRA API inizia con https://phaidra.cab.unipd.it/api/.
Azione delle PHAIDRA API

È l'azione che si vuole compiere mediante le PHAIDRA API. Si compone di un prefisso che individua il tipo di azione da compiere ed il metodo delle API da invocare. Può essere composta come:

  • object/o:NNNNNN/ + metodo_PHAIDRA_API
  • collection/o:NNNNNN/ + metodo_PHAIDRA_API

dove o:NNNNNN è l'identificatore dell'oggetto o della collezione in PHAIDRA e metodo_PHAIDRA_API è uno dei metodi delle API invocabili.

Parametri della richiesta alle PHAIDRA API
  • Il carattere ? indica che le coppie nome_parametro=valore_parametro saranno aggiunte alla richiesta e dovranno essere elaborate dal server che le riceve.
  • Se è presente più di una coppia nome_parametro=valore_parametro, le coppie dovranno essere separate dal carattere & (AND logico).
  • I parametri dipendono dal metodo delle API invocato e possono essere opzionali.

Effettuare le richieste alle PHAIDRA API

Per ognuno dei punti seguenti copiate e incollate le URL in una nuova scheda del browser web.

1. Dublin Core di un oggetto

Restituisce i metadati, secondo lo schema Dublin Core, di un oggetto presente in PHAIDRA.

https://phaidra.cab.unipd.it/api/object/o:144939/dc?format=xml

nome_parametro valore_parametro
format xml
<oai_dc:dc xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:oai_dc="http://www.openarchives.org/OAI/2.0/oai_dc/">
  <dc:rights>All rights reserved</dc:rights>
  <dc:source>Biblioteca di Storia, Perg.Sto.1/A</dc:source>
  <dc:coverage xml:lang="ita">XII, Italia, Veneto, Padova </dc:coverage>
  <dc:language>lat</dc:language>
  <dc:subject xml:lang="ita">Pergamena, S. Maria delle Carceri, Montagnana, Scodosia</dc:subject>
  <dc:description xml:lang="ita">Recto.

Sommario degli argomenti [in favore di S. Maria delle  Carceri] da provare in giudizio, relativi soprattutto all’appartenenza di Montagnana alla Scodosia, con i nominativi dei relativi testimoni.

Scrittura semplice [A].

Il documento era stato realizzato in due fogli (A e B), originariamente cuciti a formare un rodulus, come attestato da una nota tergale, ed oggi separati.

“Le pergamene del Dipartimento di Storia dell’Università di Padova 1199-1236”, p.3-7.
http://catalogo.unipd.it/F?func=find-c&amp;ccl_term=IDN=PUV0777252&amp;local_base=SBP01</dc:description>
  <dc:identifier>hdl:11168/11.144939</dc:identifier>
  <dc:identifier>http://phaidra.cab.unipd.it/o:144939</dc:identifier>
  <dc:format>image/jpeg (1348603 bytes)</dc:format>
  <dc:format>manuscript (width: 150 mm, height: 450 mm)</dc:format>
  <dc:relation>http://phaidra.cab.unipd.it/o:145104</dc:relation>
  <dc:relation>http://phaidra.cab.unipd.it/o:152073</dc:relation>
  <dc:title xml:lang="ita">XII secolo (prima del 1199 novembre 5) - (A )</dc:title>
  <dc:type xml:lang="eng">Image</dc:type>
  <dc:publisher>PHAIDRA University of Padova</dc:publisher>
  <dc:contributor>Università di Padova - Biblioteca di Storia (Digitiser)</dc:contributor>
</oai_dc:dc>

Se non si fornisce alcun parametro nella richiesta, il Dublin Core di un oggetto in PHAIDRA è restituito dalle API in formato JSON.

Solitamente nel browser un testo in formato JSON viene visualizzato come un'unica stringa di caratteri. Per ottenere una visualizzazione più leggibile si può far uso di servizi online come http://jsbeautifier.org/.

https://phaidra.cab.unipd.it/api/object/o:144939/dc

{
  "metadata": {
    "alerts": [],
    "dc": [{
      "ui_value": "All rights reserved",
      "xmlname": "rights"
    }, {
      "ui_value": "Biblioteca di Storia, Perg.Sto.1\/A",
      "xmlname": "source"
    }, {
      "attributes": [{
        "ui_value": "ita",
        "xmlname": "xml:lang"
      }],
      "ui_value": "XII, Italia, Veneto, Padova ",
      "xmlname": "coverage"
    }, {
      "ui_value": "lat",
      "xmlname": "language"
    }, {
      "attributes": [{
        "ui_value": "ita",
        "xmlname": "xml:lang"
      }],
      "ui_value": "Pergamena, S. Maria delle Carceri, Montagnana, Scodosia",
      "xmlname": "subject"
    }, {
      "attributes": [{
        "ui_value": "ita",
        "xmlname": "xml:lang"
      }],
      "ui_value": "Recto.\n\nSommario degli argomenti [in favore di S. Maria delle  Carceri] da provare in giudizio, relativi soprattutto all’appartenenza di Montagnana alla Scodosia, con i nominativi dei relativi testimoni.\n\nScrittura semplice [A].\n\nIl documento era stato realizzato in due fogli (A e B), originariamente cuciti a formare un rodulus, come attestato da una nota tergale, ed oggi separati.\n\n“Le pergamene del Dipartimento di Storia dell’Università di Padova 1199-1236”, p.3-7.\nhttp:\/\/catalogo.unipd.it\/F?func=find-c&amp;ccl_term=IDN=PUV0777252&amp;local_base=SBP01",
      "xmlname": "description"
    }, {
      "ui_value": "hdl:11168\/11.144939",
      "xmlname": "identifier"
    }, {
      "ui_value": "http:\/\/phaidra.cab.unipd.it\/o:144939",
      "xmlname": "identifier"
    },
    [...]
    {
      "ui_value": "PHAIDRA University of Padova",
      "xmlname": "publisher"
    }, {
      "ui_value": "Università di Padova - Biblioteca di Storia (Digitiser)",
      "xmlname": "contributor"
    }],
    "status": 200
  }
}

2. Metadati museali

https://phaidra.cab.unipd.it/api/object/o:333565/museo?format=xml

nome_parametro valore_parametro
format xml
<schede>
  <OA>
    <CD hint="CODICI">
      <TSK hint="Tipo scheda">OA</TSK>
    </CD>
    <AC hint="ALTRI CODICI">
      <ACC hint="Altro codice bene">MB5</ACC>
    </AC>
    <OG hint="OGGETTO">
      <OGT hint="OGGETTO">
        <OGTD hint="Definizione">Statuetta</OGTD>
      </OGT>
      <SGT hint="SOGGETTO">
        <SGTI hint="Identificazione">San Giovanni Battista</SGTI>
      </SGT>
    </OG>
    <LC hint="LOCALIZZAZIONE GEOGRAFICO-AMMINISTRATIVA">
      <LDC hint="COLLOCAZIONE SPECIFICA">
        <LDCM hint="Denominazione raccolta">Museo di Scienze Archeologiche e d&apos;Arte</LDCM>
      </LDC>
    </LC>
    <LA hint="ALTRE LOCALIZZAZIONI GEOGRAFICO-AMMINISTRATIVE">
      <TCL hint="Tipo di localizzazione">Provenienza</TCL>
      <PRV hint="LOCALIZZAZIONE GEOGRAFICO-AMMINISTRATIVA">
        <PRVS hint="Stato">Italia</PRVS>
        <PRVR hint="Regione">Veneto</PRVR>
        <PRVP hint="Provincia">PD</PRVP>
        <PRVC hint="Comune">Padova</PRVC>
      </PRV>
      <PRC hint="COLLOCAZIONE SPECIFICA">
        <PRCM hint="Denominazione raccolta">Collezione Mantova Benavides</PRCM>
      </PRC>
    </LA>
    <LA hint="ALTRE LOCALIZZAZIONI GEOGRAFICO-AMMINISTRATIVE">
      <TCL hint="Tipo di localizzazione">Provenienza</TCL>
      <PRV hint="LOCALIZZAZIONE GEOGRAFICO-AMMINISTRATIVA">
        <PRVS hint="Stato">Italia</PRVS>
        <PRVR hint="Regione">Veneto</PRVR>
        <PRVP hint="Provincia">PD</PRVP>
        <PRVC hint="Comune">Padova</PRVC>
      </PRV>
      <PRC hint="COLLOCAZIONE SPECIFICA">
        <PRCM hint="Denominazione raccolta">Collezione Vallisneri</PRCM>
      </PRC>
    </LA>
    <DT hint="CRONOLOGIA">
      <DTZ hint="CRONOLOGIA GENERICA">
        <DTZG hint="Secolo">sec. XVI</DTZG>
        <DTZS hint="Frazione di secolo">Inizio</DTZS>
      </DTZ>
    </DT>
    <AU hint="DEFINIZIONE CULTURALE">
      <ATB hint="AMBITO CULTURALE">
        <ATBD hint="Denominazione">bottega dei Lombardo</ATBD>
      </ATB>
    </AU>
    <MT hint="DATI TECNICI">
      <MTC hint="Materia e tecnica">Marmo/ scalpellatura/ levigatura</MTC>
      <MIS hint="MISURE">
        <MISU hint="Unità">cm</MISU>
        <MISA hint="Altezza">54</MISA>
        <MISL hint="Larghezza">20.5</MISL>
      </MIS>
    </MT>
    <DA hint="DATI ANALITICI">
      <DES hint="DESCRIZIONE">
        <DESO hint="Indicazioni sull&apos;oggetto">Statua maschile stante conservata in due parti. Il personaggio rappresentato è San Giovanni Battista. Il santo è rappresentato stante: il vestito di pelle appare allo stato di abbozzo, ugualmente è abbozzato il braccio sinistro che, forse, reggeva un oggetto. Sempre sulla sinistra, addossata alla veste, resta piccola parte di una pianta (palma?) di cui si intravvede sul basamento, a lato del piede sinistro, un piccolo tratto del tronco. La critica, approfondendo l&apos;analisi dell&apos;opera e i confronti con altre opere di sicura attribuzione, è arrivata a proporne la realizzazione alla bottega dei Lombardo.</DESO>
      </DES>
    </DA>
    <TU hint="CONDIZIONE GIURIDICA E VINCOLI">
      <CDG hint="CONDIZIONE GIURIDICA">
        <CDGS hint="Indicazione specifica">Università degli Studi di Padova</CDGS>
      </CDG>
    </TU>
    <DO hint="FONTI E DOCUMENTI DI RIFERIMENTO">
      <BIL hint="Citazione completa">Benacchio Flores D&apos;Arcais Malvina , Vita e opere di Tiziano Aspetti VI, in Bollettino del Museo Civico di Padova, X-XI (1934-39), pp. 96-100.</BIL>
      <BIL hint="Citazione completa">Semenzato Camillo, Alcune opere della Raccolta Benavides al Liviano, in Bollettino del Museo Civico di Padova, XLV (1956), p. 110, n. X, nota 13.</BIL>
      <BIL hint="Citazione completa">Attardi Luisa, 102. San Giovanni Battista, in Un Museo di Antichità nella Padova del Cinquecento. La raccolta di Marco Mantova Benavides all&apos;Università di Padova, a cura di Irene Favaretto, Alessandra Menegazzi, Roma, Giorgio Bretschneider, 2013, pp.127-128.</BIL>
    </DO>
  </OA>
</schede>

3. Oggetti membri di una collezione

Restituisce gli oggetti membri di una collezione presente in PHAIDRA.

https://phaidra.cab.unipd.it/api/collection/o:152073/members

{
  "alerts": [],
  "metadata": {
    "members": [{
      "pid": "o:145794",
      "pos": null
    }, {
      "pid": "o:147516",
      "pos": null
    }, {
      "pid": "o:147426",
      "pos": null
    },
    [...]
    {
      "pid": "o:145913",
      "pos": null
    }, {
      "pid": "o:145226",
      "pos": null
    }, {
      "pid": "o:147379",
      "pos": null
    }]
  }
}

Proviamo alcune chiamate alle PHAIDRA API

1. Ottenere il Dublin Core (come documento XML) dell'oggetto https://phaidra.cab.unipd.it/o:46317

  • baseurl: https://phaidra.cab.unipd.it/api/
  • azione: object/o:46317/dc
  • parametri: format=xml

https://phaidra.cab.unipd.it/api/ + object/o:46317/dc + ? + format=xml

2. Ottenere il Dublin Core (in formato JSON) dell'oggetto https://phaidra.cab.unipd.it/o:46317

  • baseurl: https://phaidra.cab.unipd.it/api/
  • azione: object/o:46317/dc

https://phaidra.cab.unipd.it/api/ + object/o:46317/dc

3. Ottenere i metadati museali (come documento XML) dell'oggetto https://phaidra.cab.unipd.it/o:72071

  • baseurl: https://phaidra.cab.unipd.it/api/
  • azione: object/o:72071/museo
  • parametri: format=xml

https://phaidra.cab.unipd.it/api/ + object/o:72071/museo + ? + format=xml

4. Ottenere l'identificatore in PHAIDRA (in formato JSON) di tutti gli oggetti membri della collezione https://phaidra.cab.unipd.it/o:268280

  • baseurl: https://phaidra.cab.unipd.it/api/
  • azione: collection/o:268280/members

https://phaidra.cab.unipd.it/api/ + collection/o:268280/members


Esempi di applicazione delle PHAIDRA API

Facendo uso dei metodi esposti dalle PHAIDRA API, è stato sviluppato un componente denominato PHAIDRA Collection Viewer che può essere incluso in un sito web esterno al fine di consentire la visualizzazione di una collezione presente in PHAIDRA.

http://mostre.cab.unipd.it/paleo/it/14/le-tavole-parietali-di-karl-alfred-von-zittel

http://mostre.cab.unipd.it/illustrazione-botanica/it/18/piante-del-r-orto-di-padova


Vai alla prossima esercitazione OAI-PMH

⚠️ **GitHub.com Fallback** ⚠️