API

• Protokół OAI-PMH
• SOAP Webservice

Udostępnianie zasobów poprzez OAI-PMH

W ramach projektu przygotowany został moduł udostępniania zasobów poprzez protokół OAI-PMH.
Serwis dostępny jest po adresem https://repozytorium.biblos.pk.edu.pl/oai-pmh
Zgodnie z definicją protokół OAI-PMH obsługuje sześć możliwych żądań definiowanych przez parametr verb. Obsługiwane żądania to:

• Identify
• ListRecords
• ListSets
• ListMetadataFormats
• ListIdentifiers
• GetRecord

Żądanie Identify

• Pierwszym z obsługiwanych żądań jest żądanie Identify. Definicja protokołu nie przewiduje dodatkowych parametrów dla tego żądania, zatem wywołanie sprowadza się do żądania: "https://repozytorium.biblos.pk.edu.pl/oai-pmh/?verb=Identify
• W odpowiedzi zwracane są podstawowe parametry identyfikujące oraz opisujące repozytorium. Dla testowej konfiguracji przykładowa odpowiedź wygląda następująco:

     

• Ponieważ w ramach serwisu dostępny jest szablon XSL/XSLT konwertujący zwracane odpowiedzi do formatu XHTML ta sama odpowiedź widziana wprost w oknie przeglądarki (obsługującej XHTML) wygląda następująco:
• Dla ułatwienia żądanie Identify stanowi domyślne żądanie serwisu. Innymi słowy przesłanie żądanie bez jakichkolwiek dodatkowych parametrów (bez wskazania wartości parametru verb) jest równoznaczne z dodaniem do żądania parametru verb=Identify.

Żądanie ListMetadataFormats

• Umożliwia uzyskanie informacji o obsługiwanych formatach odpowiedzi
• Wywołanie: https://repozytorium.biblos.pk.edu.pl/oai-pmh/?verb=ListMetadataFormats
• W ramach odpowiedzi uzyskujemy informacje o obsługiwanych formatach:
• lub w wersji ostylowanej:
• Jak widać aktualnie obsługiwane są dwa formaty odpowiedzi: DublinCore o schemacie jak poniżej, ktory stanowi domyślny format serwisu oraz IEEE Learning Object Metadata

Żądanie ListSets

• Umożliwia uzyskanie informacji o wszystkich udostępnianych w ramach danego repozytorium zbiorach/kolekcjach zasobów.
• Wywołanie:https://repozytorium.biblos.pk.edu.pl/oai-pmh/?verb=ListSets
• W ramach odpowiedzi uzyskujemy informacje o udostępnianych kolekcjach:
• lub w wersji ostylowanej:
• Jak widać w przytoczonej przykładowej konfiguracji udostępniane są trzy kolekcje:
  • Artykuły i czasopisma o identyfikatorze 8236 (do zbioru tego należą wszystkie zasobu którego jednym z przodków jest zasób o numerze 8236)
  • Publikacje książkowe o identyfikatorze 8240 (do zbioru tego należą wszystkie zasobu którego jednym z przodków jest zasób o numerze 8240)
  • Materiały konferencyjne o identyfikatorze 3638 (do zbioru tego należą wszystkie zasobu którego jednym z przodków jest zasób o numerze 3638)

Żądanie ListIdentifiers

• Umożliwia uzyskanie identyfikatorów (wszystkich bądź należących do konkretnej kolekcji) zasobów udostępnianych przez repozytorium
• Wywołanie: https://repozytorium.biblos.pk.edu.pl/oai-pmh/?verb=ListIdentifiers
• W ramach odpowiedzi uzyskujemy informacje o identyfikatorach wszystkich udostępnianych przez repozytorium zasobach:
• lub w wersji ostylowanej:
  
• Identyfikator zasobu budowany jest jako konkatenacja: nazwy protokołu (oai), identyfikatora repozytorium (w przykładowej konfiguracji: repozytorium.biblos.pk.edu.pl) oraz numeru identyfikującego zasób (np: 35426). A zatem przykładowy identyfikator przyjmuje postać: oai:repozytorium.biblos.pk.edu.pl:35426. Wspomniany numer identyfikujący zasób (ostatni element identyfikatora) to w aktualnej konfiguracji bazodanowy identyfikator zasobu.
• Żądanie ListIdentifiers może przyjmować dodatkowe parametry:
  • set - umożliwia ograniczenie zwracania listy identyfikatorów do tych przypisanych do określonego zbioru/kolekcji
    • Przykładowe wywołanie https://repozytorium.biblos.pk.edu.pl/oai-pmh/?verb=ListIdentifiers&set=8240 - spowoduje ograniczenie zbioru zwracanych identyfikatorów do tych należących do kolekcji o identyfikatorze 8240. Jako wartości parametru set podać można dowolny z identyfikatorów zwracanych przez żądanie ListSets
  • resumptionToken - zgodnie ze specyfikacją protokołu OAI-PMH zasoby zwracane są w "porcjach" o ilości rekordów zależnej od konfiguracji. Jeżeli zwrócona odpowiedź nie wyczerpuje listy wszystkich zasobów spełniających określone kryteria jednak pozostała część nie została zwrócona z uwagi na ograniczenie ilości jednorazowo zwracanych rekordów istnieje możliwość wysłania żądania zwracającego kolejną (lub dowolną inną) "porcję" danych - wówczas do żądania dodawany jest parametr resumptionToken.
    • A zatem do odpowiedzi, która nie jest "końcową" porcją identyfikatorów spełniających określone kryteria dodawany jest parametr resumptionToken, jak poniżej:
    • lub w wersji ostylowanej:
      
    • następnie, znając wartość tego parametru możemy "przejść" do kolejnej (lub dowolnej identyfikowanej przez wartość parametru resumptionToken) porcji danych poprzez dodanie do żądania parametru resumptionToken: z żądaną wartością: ttps://repozytorium.biblos.pk.edu.pl/oai-pmh/?verb=ListIdentifiers&resumptionToken=1556704816724

Żądanie ListRecords

• Umożliwa uzyskanie listy (wszystkich) udostępnianych przez repozytorium poprzez OAI-PMH zasobów.
• Domyślne wywołanie: https://repozytorium.biblos.pk.edu.pl/oai-pmh/?verb=ListRecords
• W odpowiedzi zwracana jest w formacie zgodnym z protokołem lista (wszystkich) udostępnianych zasobów:
• lub też z uwzględnieniem arkusza stylów ta sama odpowiedź widziana wprost w oknie przeglądarki (obsługującej XHTML) wygląda następująco:
  
• Żądanie ListRecords może przyjmować dodatkowe parametry:
  • metadataPrefix - umożliwa zdefiniowanie w jakim formacie powinna zostać zwrócona lista zasobów. Aktualnie obsługiwane formaty a w ślad za tym akceptowane wartości parametru metadataPrefic to: oai_dc oraz oai_lom. Dodanie do żądania tego parametru wymusza zwrócenie odpowiedzi odpowiednio w formacie DublinCore (oai_dc) lub w formacie IEEE Learning Object Metadata (oai_lom). 
    • metadataPrefix=oai_dc wymusza zwrócenie listy rekordów w formacie DublinCore.
      • Wywołanie: https://repozytorium.biblos.pk.edu.pl/oai-pmh/?verb=ListRecords&metadataPrefix=oai_dc
      • Przykładowa odpowiedź:
      • Przykładowa odpowiedź z uwzględnieniem stylowania:
      • W przygotowanym rozwiązaniu przyjęto, że domyślnym formatem odpowiedzi jest format DublinCore. Zatem brak podania w żądaniu ListRecords parametru metadataPrefix jest tożsame z dodaniem do żądania parametru: metadataPrefix=oai_dc
    • metadataPrefix=oai_lom powoduje zwrócenie listy rekordów w formacie IEEE Learning Object Metadata.
      • Wywołanie: https://repozytorium.biblos.pk.edu.pl/oai-pmh/?verb=ListRecords&metadataPrefix=oai_lom
      • Przykładowa odpowiedź:
      • Przykładowa odpowiedź z uwzględnieniem stylowania:
  • set - umożliwia ograniczenie zwracania listy rekordów do tych przypisanych do określonego zbioru/kolekcji
    • Przykładowe wywołanie https://repozytorium.biblos.pk.edu.pl/oai-pmh/?verb=ListRecords&set=8240 - spowoduje ograniczenie zbioru zwracanych rekordów do tych należących do kolekcji o identyfikatorze 8240. Jako wartości tego parametru podać można dowolny z identyfikatorów zwracanych przez żądanie ListSets
    • parametr set może być łączony z parametrem metadataPrefix co spowoduje zwrócenie listy rekordów z podanej kolekcji w formacie DublinCore (format domyślny) lub IEEE LOM. A zatem możliwe są wywołania
      • https://repozytorium.biblos.pk.edu.pl/oai-pmh/?verb=ListRecords&metadataPrefix=oai_dc&set=8240
      • https://repozytorium.biblos.pk.edu.pl/oai-pmh/?verb=ListRecords&metadataPrefix=oai_lom&set=8240
  • resumptionToken - zgodnie ze specyfikacją protokołu OAI-PMH zasoby zwracane są w "porcjach" o ilości rekordów zależnej od konfiguracji. Jeżeli zwrócona odpowiedź nie wyczerpuje listy wszystkich zasobów spełniających określone kryteria jednak nie została zwrócona z uwagi na ograniczenie ilości jednorazowo zwracanych rekordów istnieje możliwość wysłania żądania zwracającego kolejną "porcję" danych - wówczas do żądania dodawanych jest parametr resumptionToken.
    • A zatem do odpowiedzi, która nie jest "końcową" porcją rekordów spełniających określone kryteria dodawany jest parametr resumptionToken, jak poniżej:
    • lub w wersji ostylowanej:
    •  następnie, znając wartość tego parametru możemy "przejść" do kolejnej (lub dowolnej identyfikowanej przez wartość parametru resumptionToken) porcji danych poprzez dodanie do żądania parametru resumptionToken: z żądaną wartością: ttps://repozytorium.biblos.pk.edu.pl/oai-pmh/?verb=ListRecords&resumptionToken=1556704816724

Konfiguracja

• Parametry konfiguracyjne serwisu zebrano w pliku biblos-app.ini podkatalogu oai-pmh projektu. W pliku tym wyróżnić można kilka sekcji:
  • sekcja[base] - zawierającej podstawowe parametry konfiguracyjne. Zawarte tam parametry:
    • xsl = "base.xsl" - ścieżka do pliku .xsl ze schematem stylowania zwracanych przez serwis odpowiedzi
  • sekcja [repository] - parametry samego repozytorium.  W dużej części parametry opisujące i identyfikujące repozytorium widoczne w odpowiedzi na żądanie Identify
    • defaultFormat = "oai_dc" - zdefiniowanie domyślnego formatu zwracanych odpowiedzi. Dopuszczalne wartości to oai_dc oraz oai_lom
    • name = "BIBLOS REPOSITORY" - nazwa repozytorium
    • identifier = "repozytorium.biblos.pk.edu.pl" - identyfikator repozytorium. Jest jednym z elementów na podstawie ktorego udowane są identyfikatory zasobów zwracane w odpowiedzi na żądanie ListIdentifiers
    • baseURL = "https://repozytorium.biblos.pk.edu.pl/oai-pmh/index.php" - adres url repozytorium
    • prefix = "oai" dodawany m.in do identyfikatora zasobów zwracanych w odpowiedzi na żądanie ListIdentifiers
    • protocolVersion = "2.0" - wersja protokołu OAI
    • earliestDatestamp = "2018-09-01" - najwczęśniejszy znacznik czasowy zasobów
    • adminEmail = "biblos@pk.edu.pl" - adres administratora repozytorium
    • metadataformats.0..... = obłsugiwane formaty odpowiedzi. Aktualnie dostępne są dwa formaty stąd w konfiguracji wpisy:
      • metadataformats.0 = ${repository.defaultFormat}
      • metadataformats.1 = "oai_lom"
    • maxrecords = 10 - maksymalna liczba rekordów zwracanych w pojedynczej odpowiedzi na żądanie GetRecords
    • maxids = 10 - maksymalna liczba identyfikatorów zasobów zwracanych w pojedynczej odpowiedzi na żądanie ListIdentifiers
    • token.path = "/var/www/tokens/ANDS_DEMO_OAIPMH_CLI_DBPD-" - ścieżka pod która zapisywane są tokeny pozwalające na pobranie kolejnych porcji danych (wartości parametru resumptionToken żądania GetRecords oraz ListIdentifiers). System musi mieć prawa zapisu do wskazanej lokalizacji
    • token.validity = 84600 - wyrażona w sekundach ważność tokenów resumptionToken
    • acqmethod = "pdo" - mechanizm pobierania danych (aktualnie sterownik PDO, jest to jedyna obsługiwana aktualnie wartość)
    • Definicja kolekcji dokonywana jest poprzez dodanie w tej sekcji pliku konfiguracyjnego par wpisów postaci:
      • parentIDs.0 = 8236
      • setNames.0 = "Artykuły i czasopisma"
    • W aktualnej konfiguracji zdefiniowane zostały trzy kolekcje. Dodanie kolejnej kolekcji to dodanie analogicznej pary:
      • parentIDs.N = ID kolekcji do udostępnienia
      • setNames.N = "Nazwa kolekcji"
  • sekcja [pdo] - sekcja ta obejmuje dwie grupy parametrów:
    • zestaw parametrów konfiguracyjnych sterownika pdo
      • rodzaj serwera bazy danych - dopuszczalne wartości to wszystkie bazy danych obsługiwane przez mechanizm PDO
      • zestaw danych dostępowych do bazy danych (host, użytkownik, hasło, nazwa bazy danych, kodowanie)
    • zestaw identyfikatorów metadanych wykorzystywanych przy pobieraniu danych i budowaniu odpowiedzi. Na przykład jednym z pól zwracanych w odpowiedzi na żądanie GetRecord jest pole Tytuł zasobu. Zgodnie z parametrem konfiguracyjnym: oaidcTitleMetaDataNumber = 3 jako tytuł zasobu zostanie zwrócona wartość metadanej o numerze 3, a zgodnie z parametrem konfiguracyjnym publisherLabelMetaDataNumber = 30 jako wydawca zwrócona zostanie zawartość metadanej o numerze 30 dla danego zasobu. Jeżeli id poszczególnych metadanych ulegną zmiane, lub jako wartości poszczególnych pól chcielibyśmy zwrócić zawartość innej metadanej - należy dokonać odpowiednich konfiguracji w tej części pliku konfiguracyjnego.

Walidacja

Poprawność przegotowanego serwisu w sensie zgodności z protokołem OAI-PMH zweryfikowana została z wykorzystaniem ogólno dostępnych walidatorów.

• https://www.openarchives.org/Register/ValidateSite
  • Wynik walidacji dla żądania Identify
  • Wynik walidacji dla pozostałych żądań:
• http://validator.oaipmh.com/
  • wynik walidacji żądania Identify:
  • Wynik walidacji dla żądania ListMetadataFormats:
  • Wynik dla żądania ListSets:
  • Wynik walidacji dla żądania ListIdentifiers:
  • Wynik walidacji dla żądania ListRecords dla formatu DublinCore
  • Wynik walidacji dla żądania ListRecords dla formatu IEEE LOM:

Udostępnianie zasobów poprzez SOAP Webservice

Informacje podstawowe

W ramach projektu przygotowana została usługa webowa do udostępniania zasobów przez protokół SOAP.
Adres podstawowy serwisu to: https://repozytorium.biblos.pk.edu.pl/oai-pmh/soap/
Dodatkowo w celu ułatwienia testowania przygotowany został klient SOAP'owy korzystający z przygotowanego serwisu.
Klient dostępny jest pod adresem: https://repozytorium.biblos.pk.edu.pl/oai-pmh/soap/RedoSoapClient.php

WSDL

WSDL do serwisu dostępny jest pod adresem: https://repozytorium.biblos.pk.edu.pl/oai-pmh/soap/?wsdl - fragment zamieszczony także poniżej:

Dostępne operacje

W celu utrzymania spójności z zasobami udostępnianymi przez protokół OAI-PMH przygotowany webservice udostępnia pięć metod będących bezpośrednimi odpowiednikami definiowanych przez OAI-PMH żądaniami: Identify, ListSets, ListIdentifiers, ListRecords. Poszczególne metody omówione zostały poniżej:

• getRepoDetails - metoda zwraca podstawowe informacje na temat repozytorium. Jest to odpowiednik żądania Identify protokołu OAI-PMH.
  • Dla requestu:
    
  • Otrzymujemy odpowiedź:
    
  • Co dla wywołania z poziomu przygotowanego klienta: https://repozytorium.biblos.pk.edu.pl/oai-pmh/soap/RedoSoapClient.php?method=getRepoDetails lub https://repozytorium.biblos.pk.edu.pl/oai-pmh/soap/RedoSoapClient.php (funkcja getRepoDetails jest domyslna dla przygotowanego klienta daje odpowiedź:
• getCollections - metoda pozwala uzyskać informacje o udostępnianych przez repozytorium kolekcjach.
  • Dla requestu:
    
  • Otrzymujemy odpowiedź:
    
  • Co dla wywołania z poziomu przygotowanego klienta: https://repozytorium.biblos.pk.edu.pl/oai-pmh/soap/RedoSoapClient.php?method=getCollections daje odpowiedź: 
• getCollectionItems - jest to odpowiednik żądania getRecords z ustawionym parametrem set protokołu OAI-PMH. Metoda przyjmuje jako parametr identyfikator kolekcji (jeden ze zwróconych przez metode getCollections) i zwraca rekordy należące do wskazanej kolekcji.
  • Dla requestu:
    
  • Otrzymujemy odpowiedź:
    
  • Dla przykładowego wywołania z poziomu przygotowanego klienta https://repozytorium.biblos.pk.edu.pl/oai-pmh/soap/RedoSoapClient.php?method=getCollectionItems&input=8236 uzyskujemy odpowiedź:
• getItems - jest to odpowiednik żądania ListRecords. Metoda zwraca listę rekordów udostępnianych przez repozytorium. 
  • Dla requestu:
    
  • Otrzymujemy odpowiedź:
    
  • Co dla wywołania https://repozytorium.biblos.pk.edu.pl/oai-pmh/soap/RedoSoapClient.php?method=getItems z poziomu przygotowanego testowego klienta uzyskujemy odpowiedź:
• getItem - jest to odpowiednik GetRecord protokołu OAI-PMH. Metoda przyjmuje identyfikator zasobu (wartości zwracane metodą getItems lub getCollectionItems) i zwraca informacje o nim. Wyniki zwracane są w formacie DublinCore.  Dla przykłądowego requestu 
  • Dla przykładowego requestu:
    
  • Daje odpowiedź:
    
  • Co dla wywołania z poziomu testowego klienta: https://repozytorium.biblos.pk.edu.pl/oai-pmh/soap/RedoSoapClient.php?method=getItem&input=oai:repozytorium.biblos.pk.edu.pl:35428 daje odpowiedź: 

Konfiguracja

Jeżeli chodzi o konfiguracje samego repozytorium tj. zarówno parametrów opisujących/identyfikujących samo rpeozytorium (dane zwracane metodą getRepoDetails), udostępnianych kolekcji (dane zwracane metodą getCollections) czy wreszcie parametrów "technicznych" takich jak parametry sterownika PDO czy numery identyfikacyjne poszczególnych metadanych które wykorzystywane są do pobierania odpowiednich danych - są one tożsame z parametrami dla serwisu OAI-PMH. Zebrane zostały ona w pliku konfiguracyjnym biblos-app.ini umieszczonym podkatalogu oai-pmh projektu a opisane zostały w sekcji dotyczącej udostępniania zasobów poprzez OAI-PMH Na potrzeby konfiguracji parametrów specyficznych dla serwisu SOAP dostępny jest oddzielny plik konfiguracyjny soap.ini dostępny w podkatalogu oai-pmh/html/soap projektu. W aktualnej wersji plik posiada jedną sekcję konfiguracyjną

Walidacja

Poprawność przygotowanego serwisu zwalidowana została na dwa sposoby:

• Poprzez przygotowanie testowego klienta - klient przygotowany został z wykorzystaniem wbudowanej w PHP klasy SoapClient gdzie w konstruktorze podajemy wsdl oraz ewentualne dodatkowe opcje.
  • W naszym przypadku realizowane jest to poprzez wywołanie:
    
  • Następnie na stworzonej instancji wywoływane są metody serwisu:
    
  • Prawidłowe utworzenie instancji tej klasy z podaniem omawianego wcześniej wsdl'a, a następnie prawidłowe działanie wywołań poszczególnych metod (prezentowane na wcześniejszych zrzutach) stanowi potwierdzenie prawidłowości działania przygotowanego serwisu.
• Korzystając z narzędzia SOAP UI PRO
  • 
  • Jak widać z powyższego zrzutu ekranowego wszystkie testy weryfikujące poszczególne metody zakończone zostały powodzeniem.