Technische documentatie

OAI-PMH Documentatie

Over OAI-PMH

OAI-PMH is een gestandaardiseerd protocol dat werkt op basis van 'Providers' en 'Harvesters'. Een provider is een applicatie die metadata ter beschikking stelt aan derde applicaties. Een harvester is een gebruiker van deze metadata. OAI-PMH stelt de gebruikers in staat om:
  • De metadata van items of collecties aan te bieden op het web (als 'provider')

  • De metadata te verbruiken (als 'harvester')

 
Het meemoo-archief gedraagt zich als data provider en kan dus jouw gearchiveerde collecties geheel of gedeeltelijk ter beschikking stellen via deze standaard. Voor use cases verwijzen we door naar deze pagina.

OAI-PMH is een gestandaardiseerd protocol. De meemoo-implementatie voldoet aan versie 2 van deze standaard. Voor de technische documentatie verwijzen we dan ook naar de documentatie van de standaard zelf: https://www.openarchives.org/OAI/openarchivesprotocol.html.

In dit document worden de voor meemoo specifieke implementatiedetails besproken zoals authenticatie, het gebruik van sets en de afhandeling van files die verwijderd werden in het meemoo-archief. Verder wordt op deze pagina een typisch scenario uitgewerkt aan de hand van het meemoo-archief.

Authenticatie

De meemoo-implementatie van OAI-PMH is niet publiek beschikbaar: enkel gebruikers die het recht hebben om bepaalde items of collecties te zien, zullen die ook kunnen raadplegen via OAI-PMH. De rechten van de gebruiker bepalen de zichtbaarheid via OAI-PMH.

De authenticatiegegevens moeten als 'Basic' HTTP Authenticatie meegegeven worden.

Gebruikers

Elke gebruiker van het meemoo-archief heeft meteen ook toegang tot de OAI-PMH API. Dit kan handig zijn om snel zaken te testen, maar voor specifieke applicaties raden we sterk aan een gebruiker te laten aanmaken voor dit doel. Het aanmaken van een dergelijk account gebeurt op eenvoudige vraag bij support@meemoo.be. Je hoeft enkel een geldig e-mailadres te voorzien, zodat het wachtwoord van deze gebruiker ingesteld kan worden.

Rechten

Standaard zullen alle items die zich in jouw meemoo-archief bevinden en die gepubliceerd zijn, beschikbaar zijn via OAI-PMH. Indien slechts een deel van de records nodig zijn in de harvestende applicatie, zijn er twee opties:
  • De harvestende applicatie staat zelf in voor de filtering

  • Er wordt een OAI-gebruiker aangemaakt die maar een deel van jouw materiaal ter beschikking stelt.

Voor de eerste optie is geen verdere configuratie nodig: de harvestende applicatie beslist zelf welke items getoond moeten worden en welke niet. Voor de tweede optie moet een specifiek account aangemaakt worden met beperkte rechten en moeten items aan dit account toegekend worden.

Voor hulp en advies omtrent deze configuratie kan je steeds terecht bij support@meemoo.be.

Endpoint en verbs

Het meemoo OAI-PMH endpoint is hier terug te vinden:  https://archief.meemoo.be/mediahaven-oai/oai. 

Volgende verbs zijn geïmplementeerd:

Use case

Algemeen

In deze paragraaf wordt een use case omschreven waarbij items die in het meemoo-archief opgeslagen zijn getoond moeten worden op een extern platform, bvb. de website van een content partner. De metadata en essence (audio, video of foto) worden hierbij lokaal opgeslagen, bijvoorbeeld in het CMS van het extern platform.

Indien de metadata in het archief geüpdatet wordt, of indien nieuwe items aan de collectie toegevoegd worden, moeten ze ook getoond worden op de externe website.

Voor deze use case gaan we ervan uit dat:
  • de items die we willen ontsluiten tot een bepaalde collectie behoren

  • er een user en paswoord beschikbaar is met toegang tot deze collectie

De use case wordt uitgewerkt in de volgende stappen:

  1. Om een initiële synchronisatie te realiseren wordt aan de hand van listrecords alle records opgehaald. De records bevatten zowel metadata als links naar de browse kopies die gebruikt kunnen worden om audio, video of foto weer te geven of te downloaden.

  2. Eens deze synchronisatie gelopen heeft worden via OAI-PMH periodiek de geüpdatete records opgevraagd. In dit voorbeeld gaan we ervan uit dat dit elke 24u gebeurt. Tijdens de update worden zowel nieuw toegevoegde items ‘geharvest’ als updates van reeds bestaande items.

Stap 1. Initiële synchronisatie

In deze stap worden alle records opgehaald. We kiezen ervoor om alle metadata van de records op te halen in mets formaat:

Call : https://archief.meemoo.be/mediahaven-oai/oai?verb=ListRecords&metadataPrefix=mets

  • we gebruiken "listRecords", waarmee we alle metadata records willen oplijsten in het archief.
  • als metadataschema gebruiken we “mets”, wat meteen alle metadata weergeeft, inclusief links naar de audio/foto of video bestanden.

Respons: De respons bevat een aantal records, waarvan we hier de eerste tonen:


(!) Let op dat de respons alle bestanden zal weergeven waar de user recht op heeft. Dat betekent dat niet alleen audio, foto of video zal teruggegeven worden maar ook (indien aanwezig) xml bestanden met rapporten omtrent kwaliteitscontrole, ondertitels, etc. Filteren in de call is niet mogelijk, dus de harvestende applicatie moet instaan voor de filtering. Dat kan op basis van het veld type (bvb. door documenten te negeren worden alle

Een respons geeft per default 25 records terug per call. Indien extra records beschikbaar zijn wordt dit aangegeven onderaan de respons:


Hierin wordt:

  • Op basis van de “completeListSize” aangegeven wat het totaal aantal records is

  • Op basis van de “cursor” aangegeven welke het eerste records is op deze pagina.

  • Een “resumptionToken” meegegeven. Indien de volgende pagina opgehaald moet worden, moet dit token aan de volgende call gelinkt worden. 

In dit voorbeeld zal de volgende call er dus als volgt uit moeten zien. De respons hierop zal records 25 t.e.m. 49 bevatten. 


call: 

https://archief.meemoo.be/mediahaven-oai/oai?verb=ListRecords&metadataPrefix=mets&resumptionToken=UMDA6MDA6MDBaLCB1bnRpbD0yMTAwLTEyLTMwVDIzOjU5OjU5WiwgdG9rZW5TdGFydD0yNX0=


Op deze manier kan de volledige lijst overlopen worden. Het is aan de harvestende applicatie om de metadata en/of de browse kopies op te slaan in de doeldatabase, bv. het CSM van de externe website.


Stap 2. Periodieke updates.

Om periodieke updates te realiseren kan gewerkt worden met datumvelden als extra parameter in de call. Stel dat we bijvoorbeeld alle records willen opvragen die sinds 1 januari 2018 om 10:00:00 toegevoegd of aangepast werden gebruik je deze request:

request: https://archief.meemoo.be/mediahaven-oai/oai?verb=ListRecords&metadataPrefix=mets&from=2018-01-01T10:00:00Z


De respons zal identiek zijn aan deze uit stap 1 maar zal typisch minder records bevatten. Ook hier wordt weer gewerkt met resumptionTokens in het geval meer dan 25 records teruggegeven moeten worden.

Om periodieke updates te faciliteren wordt dit type request periodiek uitgevoerd. 


Geavanceerde concepten


Gebruik van sets

De meemoo-implementatie ondersteunt sets. Op dit moment worden sets gedefinieerd op het niveau van content providers.

Omgaan met verwijderde items

Op dit moment is er beperkte support voor verwijderde items. Records die uit het meemoo-archief verwijderd werden, zullen niet meer zichtbaar zijn met de verbs ListIdentifiers en ListRecords. Een GetRecord-request zal een foutmelding opleveren waaruit afgeleid kan worden dat het record gedeletet werd.

Organisaties die records deleten en willen controleren of alle harvested records nog steeds up to date zijn, moeten af en toe alle items bevragen aan de hand van GetRecord.

In de toekomst en op vraag van CP's kan het delete-support verhoogd worden naar persistent of transient.

Contacteer support@meemoo.be indien je hier vragende partij voor bent.